Interface Fluxzero

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
DefaultFluxzero
public interface Fluxzero extends AutoCloseable
High-level entry point for all interactions with the Fluxzero Runtime.

This interface exposes static convenience methods to publish and track messages, interact with aggregates, schedule tasks, index/search documents, and more. It is designed to reduce boilerplate and promote location transparency in message-driven systems.

Usage Patterns

Most applications will never need to hold or inject a Fluxzero instance directly. Instead, the Java SDK automatically binds the relevant instance to a thread-local scope, allowing access via static methods.

A concrete instance is typically constructed using DefaultFluxzero.

  • Field Details

    • applicationInstance

      static final AtomicReference<Fluxzero> applicationInstance
      Fluxzero instance set by the current application. Used as a fallback when no threadlocal instance was set. This is added as a convenience for applications that never have more than one than Fluxzero instance which will be the case for nearly all applications. On application startup simply fill this application instance.

    • instance

      static final ThreadLocal<Fluxzero> instance
      Thread-local binding of the current Fluxzero instance.

      This is automatically set during message processing to ensure that handlers can invoke commands, queries, or schedule events without explicitly injecting dependencies.

      Example: Inside a @HandleCommand method, you can call Fluxzero.sendCommand(...) and it will automatically use the correct instance, without needing manual wiring.

  • Method Details

    • get

      static Fluxzero get()
      Returns the Fluxzero instance bound to the current thread or else set by the current application. Throws an exception if no instance was registered.

    • getOptionally

      static Optional<Fluxzero> getOptionally()
      Returns the Fluxzero client bound to the current thread or else set by the current application as Optional. Returns an empty Optional if no instance was registered.

    • currentClock

      static Clock currentClock()
      Gets the clock of the current Fluxzero instance (obtained via getOptionally()). If there is no current instance the system's UTC clock is returned.

    • currentTime

      static Instant currentTime()
      Gets the time according to the current Fluxzero clock (obtained via currentClock()). If there is no current Fluxzero instance the system's UTC time is returned.

    • memoize

      static void memoize(Object key, Object value)
      Stores the given value in a memoization store that is scoped to the current Fluxzero instance and the calling class.

    • memoize

      static void memoize(Object key, Object value, Duration lifespan)
      Stores the given value in a memoization store that is scoped to the current Fluxzero instance and the calling class, evicting it after the given lifespan.

    • memoizeGlobally

      static void memoizeGlobally(Object key, Object value)
      Stores the given value in a memoization store that is scoped only to the current Fluxzero instance.

    • memoizeGlobally

      static void memoizeGlobally(Object key, Object value, Duration lifespan)
      Stores the given value in a memoization store that is scoped only to the current Fluxzero instance, evicting it after the given lifespan.

    • memoize

      static <K,V> V memoize(K key, BiFunction<K,V,V> supplier)
      Computes and stores a memoized value in a scope bound to the current Fluxzero instance and the calling class.

    • memoize

      static <K,V> V memoize(K key, BiFunction<K,V,V> supplier, Duration lifespan)
      Computes and stores a memoized value in a scope bound to the current Fluxzero instance and the calling class, evicting it after the given lifespan.

    • memoizeGlobally

      static <K,V> V memoizeGlobally(K key, BiFunction<K,V,V> supplier)
      Computes and stores a memoized value in a scope bound only to the current Fluxzero instance.

    • memoizeGlobally

      static <K,V> V memoizeGlobally(K key, BiFunction<K,V,V> supplier, Duration lifespan)
      Computes and stores a memoized value in a scope bound only to the current Fluxzero instance, evicting it after the given lifespan.

    • memoizeIfAbsent

      static <K,V> V memoizeIfAbsent(K key, Function<K,V> supplier)
      Returns the memoized value for the given key in the scope of the current calling class, computing it only when absent or expired.

    • memoizeIfAbsent

      static <K,V> V memoizeIfAbsent(K key, Function<K,V> supplier, Duration lifespan)
      Returns the memoized value for the given key in the scope of the current calling class, computing it only when absent or expired and evicting it after the given lifespan.

    • memoizeGloballyIfAbsent

      static <K,V> V memoizeGloballyIfAbsent(K key, Function<K,V> supplier)
      Returns the memoized value for the given key in the global scope of the current Fluxzero instance, computing it only when absent or expired.

    • memoizeGloballyIfAbsent

      static <K,V> V memoizeGloballyIfAbsent(K key, Function<K,V> supplier, Duration lifespan)
      Returns the memoized value for the given key in the global scope of the current Fluxzero instance, computing it only when absent or expired and evicting it after the given lifespan.

    • getMemoized

      static <K,V> V getMemoized(K key)
      Returns the memoized value for the given key in the scope of the current calling class.

    • getGloballyMemoized

      static <K,V> V getGloballyMemoized(K key)
      Returns the memoized value for the given key in the global scope of the current Fluxzero instance.

    • generateId

      static String generateId()
      Generates a functional ID using the current IdentityProvider. This is typically used for application-level entities such as aggregates or user-defined messages.
      Returns:
      a unique, traceable identifier string

    • generateId

      static <T extends Id<?>> T generateId(Class<T> idClass)
      Generates a strongly typed ID of given idClass using the current IdentityProvider.
      Returns:
      a unique, traceable typed identifier

    • idForName

      static String idForName(String name)
      Generates an ID derived from the given name using the current IdentityProvider.

      For a given name, this method always returns the same identifier.

      Parameters:
      name - the name to derive the identifier from
      Returns:
      a unique, traceable identifier string

    • currentIdentityProvider

      static IdentityProvider currentIdentityProvider()
      Fetches the configured identity provider used for both functional and technical IDs. The default is a UuidFactory that generates UUIDs.

      If there is no current Fluxzero instance, a new UUID factory is generated.

    • currentCorrelationData

      static Map<String,String> currentCorrelationData()
      Gets the current correlation data, which by default depends on the current Client, Tracker and DeserializingMessage

    • publishEvent

      static void publishEvent(Object event)
      Publishes the given application event. The event may be an instance of a Message in which case it will be published as is. Otherwise the event is published using the passed value as payload without additional metadata.

      Note: These events are not persisted for event sourcing. To publish domain events as part of an aggregate lifecycle, apply the events using Entity.apply(Object...) after loading an entity.

      See Also:

    • publishEvent

      static void publishEvent(Object payload, io.fluxzero.common.api.Metadata metadata)
      Publishes an event with given payload and metadata.

      Note: These events are not persisted for event sourcing. To publish domain events as part of an aggregate lifecycle, apply the events using Entity.apply(Object...) after loading an entity.

      See Also:

    • publishEvents

      static void publishEvents(Object... events)
      Publishes given application events. The events may be instances of Message in which case they will be published as is. Otherwise, the events are published using the passed value as payload without additional metadata.

      Note: These events are not persisted for event sourcing. To publish domain events as part of an aggregate lifecycle, apply the events using Entity.apply(Object...) after loading an entity.

      See Also:

    • sendAndForgetCommand

      static void sendAndForgetCommand(Object command)
      Sends the given command and doesn't wait for a result. The command may be an instance of a Message in which case it will be sent as is. Otherwise the command is published using the passed value as payload without additional metadata.
      See Also:

    • sendAndForgetCommands

      static void sendAndForgetCommands(Object... commands)
      Sends the given commands and doesn't wait for results. Commands may be an instance of a Message in which case it will be sent as is. Otherwise, the commands are published using the passed value as payload without additional metadata.
      See Also:

    • sendAndForgetCommand

      static void sendAndForgetCommand(Object payload, io.fluxzero.common.api.Metadata metadata)
      Sends a command with given payload and metadata and don't wait for a result.
      See Also:

    • sendAndForgetCommand

      static void sendAndForgetCommand(Object payload, io.fluxzero.common.api.Metadata metadata, io.fluxzero.common.Guarantee guarantee)
      Sends a command with given payload and metadata and don't wait for a result. With a guarantee the method will wait for the command itself to be sent or stored.
      See Also:

    • sendCommand

      static <R> CompletableFuture<R> sendCommand(Object command)
      Sends the given command and returns a future that will be completed with the command's result. The command may be an instance of a Message in which case it will be sent as is. Otherwise the command is published using the passed value as payload without additional metadata.

    • sendCommand

      static <R> CompletableFuture<R> sendCommand(Request<R> command)
      Sends the given command and returns a future that will be completed with the command's result. The command may be an instance of a Message in which case it will be sent as is. Otherwise the command is published using the passed value as payload without additional metadata.

      The return type is determined by the given command.

    • sendCommands

      static <R> List<CompletableFuture<R>> sendCommands(Object... commands)
      Sends the given commands and returns a list of futures that will be completed with the commands' results. The commands may be instances of a Message in which case they will be sent as is. Otherwise, the commands are published using the passed values as payload without additional metadata.

    • sendCommand

      static <R> CompletableFuture<R> sendCommand(Object payload, io.fluxzero.common.api.Metadata metadata)
      Sends a command with given payload and metadata and returns a future that will be completed with the command's result.

    • sendCommand

      static <R> CompletableFuture<R> sendCommand(Request<R> payload, io.fluxzero.common.api.Metadata metadata)
      Sends a command with given payload and metadata and returns a future that will be completed with the command's result.

      The return type is determined by the given command.

    • sendCommandAndWait

      static <R> R sendCommandAndWait(Object command)
      Sends the given command and returns the command's result. The command may be an instance of a Message in which case it will be sent as is. Otherwise, the command is published using the passed value as payload without additional metadata.

    • sendCommandAndWait

      static <R> R sendCommandAndWait(Request<R> command)
      Sends the given command and returns the command's result. The command may be an instance of a Message in which case it will be sent as is. Otherwise, the command is published using the passed value as payload without additional metadata.

      The return type is determined by the given command.

    • sendCommandAndWait

      static <R> R sendCommandAndWait(Object payload, io.fluxzero.common.api.Metadata metadata)
      Sends a command with given payload and metadata and returns a future that will be completed with the command's result.

    • sendCommandAndWait

      static <R> R sendCommandAndWait(Request<R> payload, io.fluxzero.common.api.Metadata metadata)
      Sends a command with given payload and metadata and returns a future that will be completed with the command's result.

      The return type is determined by the given command.

    • assertLegal

      static void assertLegal(Object update)
      Runs apply interceptors and immediate model assertions declared for the given update without invoking applies or committing model changes.

      Assertions marked with AssertLegal.afterHandler() are not invoked because this validation-only operation does not produce a post-apply model state. This enters the model pipeline directly and does not dispatch the update as a command.

      Parameters:
      update - the update payload or message to validate

    • assertLegal

      static void assertLegal(Object update, io.fluxzero.common.api.Metadata metadata)
      Runs apply interceptors and immediate model assertions with the supplied metadata, without invoking applies or committing model changes.
      Parameters:
      update - the update payload to validate
      metadata - metadata available to interceptors and assertions

    • assertAndApply

      static void assertAndApply(Object update)
      Runs the model assertions, apply interceptors, and applies declared for the given update and waits until the resulting model commit has been committed. If this application has no locally reachable model apply, immediate assertions and apply interceptors still run, after which the call logs a warning and returns without committing.

      This enters the model-commit pipeline directly. It does not dispatch the update as a command and therefore can safely be called from an explicit HandleCommand handler for the same payload type.

      Parameters:
      update - the update payload or message to assert and apply

    • assertAndApply

      static void assertAndApply(Object update, io.fluxzero.common.api.Metadata metadata)
      Runs and commits a model commit with the supplied metadata.
      Parameters:
      update - the update payload to assert and apply
      metadata - metadata to attach to the model event

    • commit

      static CompletableFuture<Void> commit()
      Commits Model changes already produced in the current handling context without waiting for its normal automatic commit boundary.

      This is an optional early flush of the existing Model commit, not a separate mutation or commit path. The returned future is the existing durable commit completion and therefore carries the same success or failure. Required predecessor commits are also released and flushed, so their ordinary batch boundary cannot prevent the current commit from completing. Independent deferred commits keep their normal commit boundary. When the current context has no pending Model changes, the method returns an already completed future and sends nothing to the Runtime. Automatic committing remains active and observes the same completion.

      Returns:
      completion of the current durable Model commit, or completed completion when no changes are pending

    • assertAndApply

      static <T> Graph<T> assertAndApply(Graph<T> target, Object update)
      Runs and commits an update against the explicitly selected model graph, independently of any model ID carried by the update payload. Interceptors, assertions, applies, event publication, conflict handling and commit guarantees are otherwise identical to assertAndApply(Object).

      Prefer Graph.assertAndApply(Object) in application code. This overload owns the direct model-pipeline bridge used by that convenience.

      Parameters:
      target - explicitly selected model graph
      update - update payload or message to assert and apply
      Returns:
      the freshly loaded graph after the durable commit

    • assertAndApply

      static <T> Graph<T> assertAndApply(Graph<T> target, Object update, io.fluxzero.common.api.Metadata metadata)
      Runs and commits an update with additional metadata against the explicitly selected model graph.
      See Also:

    • assertAndApplyAsync

      static CompletableFuture<Void> assertAndApplyAsync(Object update)
      Runs the model assertions, apply interceptors, and applies declared for the given update without blocking the caller, and completes after the resulting model commit has been durably stored.

      The update is converted to a message before this method returns, so metadata and context inherited from the current handler remain available to the asynchronous commit pipeline.

      Parameters:
      update - the update payload or message to assert and apply
      Returns:
      completion of the durable model commit

    • assertAndApplyAsync

      static CompletableFuture<Void> assertAndApplyAsync(Object update, io.fluxzero.common.api.Metadata metadata)
      Runs and commits a model commit asynchronously with the supplied metadata.
      Parameters:
      update - the update payload to assert and apply
      metadata - metadata to attach to the model event
      Returns:
      completion of the durable model commit

    • assertAndApplyAllAsync

      static CompletableFuture<Void> assertAndApplyAllAsync(Collection<?> updates)
      Runs and commits multiple independent model updates asynchronously. Every update remains a separate model commit with its own conflict handling and durability boundary. Implementations may batch commits that become ready together for transport, without making the updates atomic or delaying already-full transport batches.

      All updates are converted to messages before this method returns, so metadata and context inherited from the current handler remain available to every asynchronous commit pipeline.

      Parameters:
      updates - independent update payloads or messages to assert and apply
      Returns:
      completion after every resulting model commit has been durably stored

    • query

      static <R> CompletableFuture<R> query(Object query)
      Sends the given query and returns a future that will be completed with the query's result. The query may be an instance of a Message in which case it will be sent as is. Otherwise, the query is published using the passed value as payload without additional metadata.

    • query

      static <R> CompletableFuture<R> query(Request<R> query)
      Sends the given query and returns a future that will be completed with the query's result. The query may be an instance of a Message in which case it will be sent as is. Otherwise, the query is published using the passed value as payload without additional metadata.

      The return type is determined by the given query.

    • query

      static <R> CompletableFuture<R> query(Object payload, io.fluxzero.common.api.Metadata metadata)
      Sends a query with given payload and metadata and returns a future that will be completed with the query's result.

    • query

      static <R> CompletableFuture<R> query(Request<R> payload, io.fluxzero.common.api.Metadata metadata)
      Sends a query with given payload and metadata and returns a future that will be completed with the query's result.

      The return type is determined by the given query.

    • queryAndWait

      static <R> R queryAndWait(Object query)
      Sends the given query and returns the query's result. The query may be an instance of a Message in which case it will be sent as is. Otherwise, the query is published using the passed value as payload without additional metadata.

    • queryAndWait

      static <R> R queryAndWait(Request<R> query)
      Sends the given query and returns the query's result. The query may be an instance of a Message in which case it will be sent as is. Otherwise, the query is published using the passed value as payload without additional metadata.

      The return type is determined by the given query.

    • queryAndWait

      static <R> R queryAndWait(Object payload, io.fluxzero.common.api.Metadata metadata)
      Sends a query with given payload and metadata and returns the query's result.

    • queryAndWait

      static <R> R queryAndWait(Request<R> payload, io.fluxzero.common.api.Metadata metadata)
      Sends a query with given payload and metadata and returns the query's result.

      The return type is determined by the given query.

    • schedulePeriodic

      static String schedulePeriodic(Object schedule)
      Starts a new periodic schedule, returning the schedule's id. The schedule parameter may be an instance of a Message or the schedule payload. If the payload is not annotated with Periodic an IllegalArgumentException is thrown.
      See Also:

    • schedulePeriodic

      static void schedulePeriodic(Object schedule, Object scheduleId)
      Starts a new periodic schedule using given schedule id. The schedule parameter may be an instance of a Message or the schedule payload. If the payload is not annotated with Periodic an IllegalArgumentException is thrown.
      See Also:

    • schedule

      static String schedule(Object schedule, Instant deadline)
      Schedules a message for the given timestamp, returning the schedule's id. The schedule parameter may be an instance of a Message in which case it will be scheduled as is. Otherwise, the schedule is published using the passed value as payload without additional metadata.

    • schedule

      static void schedule(Object schedule, Object scheduleId, Instant deadline)
      Schedules a message with given scheduleId for the given timestamp. The schedule parameter may be an instance of a Message in which case it will be scheduled as is. Otherwise, the schedule is published using the passed value as payload without additional metadata.

    • schedule

      static String schedule(Object schedule, Duration delay)
      Schedules a message after the given delay, returning the schedule's id. The schedule parameter may be an instance of a Message in which case it will be scheduled as is. Otherwise, the schedule is published using the passed value as payload without additional metadata.

    • schedule

      static void schedule(Object schedule, Object scheduleId, Duration delay)
      Schedules a message with given scheduleId after given delay. The schedule parameter may be an instance of a Message in which case it will be scheduled as is. Otherwise, the schedule is published using the passed value as payload without additional metadata.

    • schedule

      static void schedule(Schedule schedule)
      Schedule a message object (of type Schedule) for execution, using the Guarantee.SENT guarantee.
      Parameters:
      schedule - the message to schedule

    • schedule

      static void schedule(Schedule schedule, boolean ifAbsent)
      Schedule a message object (of type Schedule) for execution, using the Guarantee.SENT guarantee.
      Parameters:
      schedule - the message to schedule

    • scheduleCommand

      static String scheduleCommand(Object command, Instant deadline)
      Schedules a command for the given timestamp, returning the command schedule's id. The command parameter may be an instance of a Message in which case it will be scheduled as is. Otherwise, the command is scheduled using the passed value as payload without additional metadata.

    • scheduleCommand

      static void scheduleCommand(Object command, Object scheduleId, Instant deadline)
      Schedules a command with given scheduleId for the given timestamp. The command parameter may be an instance of a Message in which case it will be scheduled as is. Otherwise, the command is published using the passed value as payload without additional metadata.

    • scheduleCommand

      static String scheduleCommand(Object command, Duration delay)
      Schedules a command after given delay, returning the command schedule's id. The command parameter may be an instance of a Message in which case it will be scheduled as is. Otherwise, the command is scheduled using the passed value as payload without additional metadata.

    • scheduleCommand

      static void scheduleCommand(Object command, Object scheduleId, Duration delay)
      Schedules a command with given scheduleId after given delay. The command parameter may be an instance of a Message in which case it will be scheduled as is. Otherwise, the command is published using the passed value as payload without additional metadata.

    • scheduleCommand

      static void scheduleCommand(Schedule message)
      Schedule a command using the given scheduling settings, using the Guarantee.SENT guarantee.

    • scheduleCommand

      static void scheduleCommand(Schedule message, boolean ifAbsent)
      Schedule a command using the given scheduling settings if no other with same ID exists, using the Guarantee.SENT guarantee.

    • cancelSchedule

      static void cancelSchedule(Object scheduleId)
      Cancels the schedule with given scheduleId.

    • sendWebRequest

      static CompletableFuture<WebResponse> sendWebRequest(WebRequest request)
      Sends the given web request using default request settings and returns a future that completes with the response.

      Proxy and native HTTP execution require an absolute URL; relative URLs may be handled by a local web handler.

    • sendWebRequest

      static CompletableFuture<WebResponse> sendWebRequest(WebRequest request, WebRequestSettings settings)
      Sends the given web request using the given request settings and returns a future that completes with the response.

      Proxy and native HTTP execution require an absolute URL; relative URLs may be handled by a local web handler.

    • sendWebRequestAndWait

      static WebResponse sendWebRequestAndWait(WebRequest request)
      Sends the given web request using default request settings and waits for the response synchronously.

      This method blocks the calling thread until the request is completed or times out.

      Proxy and native HTTP execution require an absolute URL; relative URLs may be handled by a local web handler.

    • sendWebRequestAndWait

      static WebResponse sendWebRequestAndWait(WebRequest request, WebRequestSettings settings)
      Sends the given web request using given request settings and waits for the response synchronously.

      This method blocks the calling thread until the request is completed or times out.

      Proxy and native HTTP execution require an absolute URL; relative URLs may be handled by a local web handler.

    • publishMetrics

      static void publishMetrics(Object metrics)
      Publishes a metrics event. The parameter may be an instance of a Message in which case it will be sent as is. Otherwise the metrics event is published using the passed value as payload without additional metadata.

      Metrics events can be published in any form to log custom performance metrics about an application.

    • publishMetrics

      static void publishMetrics(Object payload, io.fluxzero.common.api.Metadata metadata)
      Publishes a metrics event with given payload and metadata. Metrics events can be published in any form to log custom performance metrics about an application.

    • loadAggregate

      static <T> Entity<T> loadAggregate(Id<T> aggregateId)
      Loads the aggregate root of type <T> with given aggregateId.

      If the aggregate is loaded while handling an event of the aggregate, the returned Aggregate will automatically be played back to the event currently being handled. Otherwise, the most recent state of the aggregate is loaded. Typed identifiers whose declared type is an independent Model are delegated to the model repository. This preserves source-compatible typed loads while migrating an aggregate root to an independent model.

      See Also:

    • loadAggregate

      static <T> Entity<T> loadAggregate(Object aggregateId)
      Loads the aggregate root with the given aggregateId. If the aggregate exists, it will be loaded and returned with its respective type, if not, an empty Entity of type Object will be returned.

      If the aggregate is loaded while handling an event of the aggregate, the returned Aggregate will automatically be played back to the event currently being handled. Otherwise, the most recent state of the aggregate is loaded.

      See Also:

    • loadAggregate

      static <T> Entity<T> loadAggregate(Object aggregateId, Class<T> aggregateType)
      Loads the aggregate root of type <T> with given aggregateId.

      If the aggregate is loaded while handling an event of the aggregate, the returned Aggregate will automatically be played back to the event currently being handled. Otherwise, the most recent state of the aggregate is loaded.

      See Also:

    • loadModel

      static <T> Entity<T> loadModel(Id<T> modelId)
      Loads the independently stored model identified by the given typed ID.

      The typed ID's repository representation is wrapped in any prefix or postfix declared by the model's @EntityId. When no primary model has that identity, a current @Alias value may resolve the model instead.

    • loadModel

      static <T> Entity<T> loadModel(Object modelId)
      Loads an independently stored model by ID. Typed IDs provide the requested model type; untyped IDs let the repository resolve the stored type.

      A primary model ID is tried first, followed by a current @Alias value.

    • loadModel

      static <T> Entity<T> loadModel(Object modelId, Class<T> modelType)
      Loads an independently stored model by ID and expected type.

      A primary model ID is tried first, followed by a current @Alias value.

    • loadModel

      static <T> Entity<T> loadModel(Object parentId, Class<?> parentType, Object modelId, Class<T> modelType)
      Loads a parent-scoped model by functional child ID and explicit parent type.

    • loadCurrentModelState

      static <T> ModelState<T> loadCurrentModelState(String modelId, Class<T> modelType)
      Reads a verified current Model document without replaying historical events. The exact persisted identity is required. The read-only result does not inherit a handler boundary or become a transaction read dependency. Missing/deleted state is distinct from an unavailable/stale document, which fails explicitly.
      See Also:

    • loadCurrentModelState

      static <T> ModelState<T> loadCurrentModelState(Id<T> modelId)
      Reads a current document-backed Model using its typed identity.

    • loadGraph

      static <T> Graph<T> loadGraph(Id<T> modelId)
      Lazily loads the independently stored model identified by the typed ID as a relationship graph.

      The source model is loaded only when its value, history or relationship contents are requested. A typed ancestor lookup can normally resolve directly from stored relationship identities.

    • loadGraph

      static Graph<?> loadGraph(Object modelId)
      Loads a model whose concrete type is resolved from storage as a lazy relationship graph. The default repository discovers its type from the head and pins the boundary during this call, without replaying the root value. The root Model contract must be locally known. Custom repositories may retain value-based discovery.

    • loadGraph

      static <T> Graph<T> loadGraph(Object modelId, Class<T> modelType)
      Lazily loads an independently stored model by ID and expected type as a relationship graph.

    • loadCurrentGraph

      static <T> Graph<T> loadCurrentGraph(Object modelId, Class<T> modelType)
      Loads the latest state of an independently stored model as a relationship graph, without inheriting an event or notification handler's historical read boundary. The default repository pins the current head during this call and defers authoritative value reconstruction until needed. This is not the document-only loadCurrentModelState(String, Class) read contract.

      Use this after a synchronous nested command when the remainder of the handler deliberately needs that command's updated Model state. Ordinary loadGraph(Object, Class) reads remain coherent with the message being handled and are therefore preferred everywhere else.

    • loadCurrentGraph

      static <T> Graph<T> loadCurrentGraph(Id<T> modelId)
      Loads the latest state of the independently stored model identified by the typed ID as a relationship graph.
      See Also:

    • loadGraph

      static <T> Graph<T> loadGraph(Object parentId, Class<?> parentType, Object modelId, Class<T> modelType)
      Lazily loads a parent-scoped model by functional child ID and explicit parent type as a relationship graph.

    • loadGraphAt

      static <T> Graph<T> loadGraphAt(Id<T> modelId, long stateIndex)
      Reconstructs a complete historical graph at the requested durable model-state boundary.

    • loadModels

      static <T> List<Entity<T>> loadModels(List<?> modelIds, Class<T> modelType)
      Loads several independently stored models at one coherent state boundary.

      The native repository batches stream I/O and reconstruction while preserving input order.

    • loadAggregateFor

      static <T> Entity<T> loadAggregateFor(Object entityId, Class<?> defaultType)
      Loads the aggregate root of type <T> that currently contains the entity with given entityId. If no such aggregate exists an empty aggregate root is returned with given defaultType as its type.

      This method can also be used if the entity is the aggregate root (aggregateId is equal to entityId). If the entity is associated with more than one aggregate the behavior of this method is unpredictable, though the default behavior is that any one of the associated aggregates is returned.

      If the aggregate is loaded while handling an event of the aggregate, the returned Aggregate will automatically be played back to the event currently being handled. Otherwise, the most recent state of the aggregate is loaded.

      See Also:

    • loadAggregateFor

      static <T> Entity<T> loadAggregateFor(Object entityId)
      Loads the aggregate root that currently contains the entity with given entityId. If no such aggregate exists an empty aggregate root is returned of type Object. In that case be aware that applying events to create the aggregate may yield an undesired result; to prevent this use loadAggregateFor(Object, Class).

      This method can also be used if the entity is the aggregate root (aggregateId is equal to entityId). If the entity is associated with more than one aggregate the behavior of this method is unpredictable, though the default behavior is that any one of the associated aggregates is returned.

      If the aggregate is loaded while handling an event of the aggregate, the returned Aggregate will automatically be played back to the event currently being handled. Otherwise, the most recent state of the aggregate is loaded.

      See Also:

    • loadEntity

      static <T> Entity<T> loadEntity(Object entityId)
      Loads the entity with given id. If the entity is not associated with any aggregate yet, a new aggregate root is loaded with the entityId as aggregate identifier. In case multiple entities are associated with the given entityId the most recent entity is returned.

      If the entity is loaded while handling an event its aggregate, the returned entity will automatically be played back to the event currently being handled. Otherwise, the most recent state of the entity is loaded.

    • loadEntity

      static <T> Entity<T> loadEntity(Id<T> entityId)
      Loads the entity with given id. If the entity is not associated with any aggregate yet, a new aggregate root is loaded with the entityId as aggregate identifier. In case multiple entities are associated with the given entityId the most recent entity is returned.

      If the entity is loaded while handling an event its aggregate, the returned entity will automatically be played back to the event currently being handled. Otherwise, the most recent state of the entity is loaded.

    • loadEntity

      static <T> Entity<T> loadEntity(Object entityId, Class<T> entityType)
      Loads an entity by functional ID and expected type. The type makes EntityId affixes available for independent models and entities embedded in legacy aggregates.

    • loadEntityValue

      static <T> T loadEntityValue(Object entityId)
      Loads the current entity value for given entity id. Entity may be the aggregate root or any ancestral entity. If no such entity exists or its value is not set null is returned.

      If the entity is loaded while handling an event its aggregate, the returned entity will automatically be played back to the event currently being handled. Otherwise, the most recent state of the entity is loaded.

    • loadEntityValue

      static <T> T loadEntityValue(Id<T> entityId)
      Loads the current entity value for given entity id. Entity may be the aggregate root or any ancestral entity. If no such entity exists or its value is not set null is returned.

      If the entity is loaded while handling an event its aggregate, the returned entity will automatically be played back to the event currently being handled. Otherwise, the most recent state of the entity is loaded.

    • loadEntityValue

      static <T> T loadEntityValue(Object entityId, Class<T> entityType)
      Loads an entity value by functional ID and expected type.

    • asEntity

      static <T> Entity<T> asEntity(T value)
      Returns an Entity containing given value. The returned entity won't exhibit any side effects when they are updated, i.e. they won't be synced to any repository or give rise to any events. Other than, that they are fully functional.

    • prepareIndex

      static IndexOperation prepareIndex(@NonNull @NonNull Object object)
      Prepare given object for indexing for search. This returns a mutable builder that allows defining an id, collection, etc.

      If the object is annotated with @Searchable the collection name and any timestamp or end path defined there will be used.

      If the object has a property annotated with EntityId, it will be used as the id of the document. Otherwise, a random id will be assigned to the document.

      This method returns once the object is stored.

      See Also:

    • index

      static CompletableFuture<Void> index(Object object)
      Index given object for search.

      If the object is annotated with @Searchable the collection name and any timestamp or end path defined there will be used.

      If the object has a property annotated with EntityId, it will be used as the id of the document. Otherwise, a random id will be assigned to the document.

      This method returns once the object is stored.

      See Also:

    • index

      static CompletableFuture<Void> index(Object object, Object collection)
      Index given object for search.

      If the object has a property annotated with EntityId, it will be used as the id of the document. Otherwise, a random id will be assigned to the document.

      This method returns once the object is stored.

      See Also:

    • index

      static CompletableFuture<Void> index(Object object, Object id, Object collection)
      Index given object for search. This method returns once the object is stored.
      See Also:

    • index

      static CompletableFuture<Void> index(Object object, Object id, Object collection, Instant timestamp)
      Index given object for search. This method returns once the object is stored.
      See Also:

    • index

      static CompletableFuture<Void> index(Object object, Object id, Object collection, Instant begin, Instant end)
      Index given object for search. This method returns once the object is stored.
      See Also:

    • index

      static <T> CompletableFuture<Void> index(Collection<? extends T> objects, Object collection, Function<? super T, String> idFunction, Function<? super T, Instant> timestampFunction, Function<? super T, Instant> endFunction)
      Index given objects for search. Use idFunction to provide the document's required id. Use timestampFunction and endFunction to provide the object's timestamp. If none are supplied the document will not be timestamped.

      This method returns once all objects are stored.

      See Also:

    • bulkUpdate

      static BulkUpdateBuilder bulkUpdate(Object collection)
      Prepare a fluent bulk update for the given document collection.

      Example usage: Fluxzero.bulkUpdate("my_collection").index(doc1).delete(doc2Id).execute();

      See Also:

    • search

      static <T> Search<T> search(Object collection)
      Search the given collection for documents. Usually collection is the String name of the collection. However, it is also possible to call it with a Collection containing one or multiple collection names.

      If collection is of type Class it is expected that the class is annotated with Searchable. It will then use the collection configured there.

      For all other inputs, the collection name will be obtained by calling Object.toString() on the input.

      Example usage: Fluxzero.<MyDocument>search("myCollection").query("foo !bar").fetch(100).

    • search

      static <T> Search<T> search(Class<T> collection)
      Search the collection represented by the given document class and retain that class as the default result type.

    • search

      static <T> Search<T> search(Class<T> collection, Object... additionalCollections)
      Search the collections represented by the given document class and additional collection identifiers while retaining the document class as the default result type.

    • search

      static <T> Search<T> search(Object collection, Object... additionalCollections)
      Search the given collections for documents.

      If collection is of type Class it is expected that the class is annotated with Searchable. It will then use the collection configured there. For all other inputs, the collection name will be obtained by calling Object.toString() on the input.

      Example usage: Fluxzero.search("myCollection", "myOtherCollection).query("foo !bar").fetch(100);

    • search

      static <T> Search<T> search(io.fluxzero.common.api.search.SearchQuery.Builder queryBuilder)
      Search documents using given reusable query builder.

      Example usage: Fluxzero.search(SearchQuery.builder().search("myCollection").query("foo !bar")).fetch(100);

    • searchGraph

      static <T> Search<Graph<T>> searchGraph(Class<T> rootModelType)
      Searches complete graph views for an independent model root. A configured materialized view is preferred; otherwise the graph is composed live.

    • searchGraph

      static <T> Search<Graph<T>> searchGraph(Class<T> rootModelType, boolean forceAdHoc)
      Searches complete graph views for an independent model root.
      Parameters:
      forceAdHoc - whether to bypass a configured materialized view and compose the current graph live

    • hasDocument

      static boolean hasDocument(Id<?> id)
      Checks whether a document exists for the given identifier and its associated type. The type is used to determine the document collection.

    • hasDocument

      static boolean hasDocument(Object id, Object collection)
      Checks if a document exists in the specified collection.

    • getDocument

      static <T> Optional<T> getDocument(Id<T> id)
      Fetches a document by id using the associated type to determine the collection. The result is deserialized into the stored type.

    • getDocument

      static <T> Optional<T> getDocument(Object id, Object collection)
      Gets the document with given id in given collection, returning the value in the type that it was stored.

    • getDocument

      static <T> Optional<T> getDocument(Object id, Class<T> collection)
      Gets the document with given id in given collection type, returning the value.

    • getDocument

      static <T> Optional<T> getDocument(Object id, Object collection, Class<T> type)
      Gets the document with given id in given collection, converting the matching document to a value with given type.

    • getDocuments

      static <T> Collection<T> getDocuments(Collection<?> ids, Object collection)
      Gets a collection of documents by their IDs from the given collection and deserializes them into the stored type.

    • getDocuments

      static <T> Collection<T> getDocuments(Collection<?> ids, Class<T> collection)
      Gets a collection of documents by their IDs from the given collection type.

    • getDocuments

      static <T> Collection<T> getDocuments(Collection<?> ids, Object collection, Class<T> type)
      Gets a collection of documents by their IDs, converting the matching documents to value with the given type.

    • deleteDocument

      static CompletableFuture<Void> deleteDocument(Object id, Object collection)
      Deletes the document with given id in given collection if it exists.

    • deleteCollection

      static CompletableFuture<Void> deleteCollection(Object collection)
      Deletes a search collection if it exists.

    • filterContent

      static <T> T filterContent(T value, User user)
      Modify given value before it's passed to the given viewer. See FilterContent for info on how to filter the value.

    • downcast

      static Object downcast(Object object, int desiredRevision)
      Downcasts the given object to a previous revision.
      Parameters:
      object - the object to downcast
      desiredRevision - the target revision
      Returns:
      a serialized form of the object downcasted to the given revision

    • downcast

      static Object downcast(io.fluxzero.common.api.Data<?> data, int desiredRevision)
      Downcasts a Data object to the specified revision level.
      Parameters:
      data - the serialized data
      desiredRevision - the target revision number
      Returns:
      a serialized form of the object downcasted to the given revision

    • registerHandlers

      default io.fluxzero.common.Registration registerHandlers(Object... handlers)
      Registers given handlers and initiates message tracking (i.e. listening for messages).

      The given handlers will be inspected for annotated handler methods (e.g. methods annotated with HandleCommand). Depending on this inspection message tracking will commence for any handled message types. To stop listening at any time invoke Registration.cancel() on the returned object.

      Note that an exception may be thrown if tracking for a given message type is already in progress.

      If any of the handlers is a local handler or contains local handler methods, i.e. if type or method is annotated with LocalHandler, the target object will (also) be registered as local handler. Local handlers will handle messages in the publishing thread. If a published message can be handled locally it will not be published to the Fluxzero Runtime. Local handling of messages may come in handy in several situations: e.g. when the message is expressly meant to be handled only by the current application or if the message needs to be handled as quickly as possible. However, in most cases it will not be necessary to register local handlers.

      Note that it will generally not be necessary to invoke this method manually if you use Spring to configure your application.

      See Also:

    • registerHandlers

      default io.fluxzero.common.Registration registerHandlers(List<?> handlers)
      Registers given handlers and initiates message tracking.
      See Also:

    • withClock

      void withClock(Clock clock)
      Have Fluxzero use the given Clock when generating timestamps, e.g. when creating a Message.

    • aggregateRepository

      AggregateRepository aggregateRepository()
      Returns a client to assist with event sourcing.

    • modelRepository

      default ModelRepository modelRepository()
      Returns the repository for independently stored models.

      The default keeps existing custom Fluxzero implementations binary/source compatible while the model action transport is introduced. Standard runtime-backed configurations override this when that transport is available.

    • eventStore

      EventStore eventStore()
      Returns the store for aggregate events.

    • snapshotStore

      SnapshotStore snapshotStore()
      Returns the store for aggregate snapshots.

    • messageScheduler

      MessageScheduler messageScheduler()
      Returns the gateway to schedule messages.
      See Also:
      • MessageType.SCHEDULE

    • commandGateway

      CommandGateway commandGateway()
      Returns the gateway for command messages.

    • queryGateway

      QueryGateway queryGateway()
      Returns the gateway for query messages.

    • eventGateway

      EventGateway eventGateway()
      Returns the message gateway for application events. Use aggregateRepository() to publish events belonging to an aggregate.

    • resultGateway

      ResultGateway resultGateway()
      Returns the gateway for result messages sent by handlers of commands and queries.

    • errorGateway

      ErrorGateway errorGateway()
      Returns the gateway for any error messages published while handling a command or query.

    • metricsGateway

      MetricsGateway metricsGateway()
      Returns the gateway for metrics events. Metrics events can be published in any form to log custom performance metrics about an application.

    • webRequestGateway

      WebRequestGateway webRequestGateway()
      Returns the gateway for sending web requests.

    • customGateway

      GenericGateway customGateway(String topic)
      Returns the gateway for given custom message topic.

    • tracking

      Tracking tracking(io.fluxzero.common.MessageType messageType)
      Returns a client to assist with the tracking of a given message type.

    • keyValueStore

      KeyValueStore keyValueStore()
      Returns a client for the key value service offered by Fluxzero.

    • documentStore

      DocumentStore documentStore()
      Returns a client for the document search service offered by Fluxzero.

    • userProvider

      UserProvider userProvider()
      Returns the UserProvider used by Fluxzero to authenticate users. May be null if user authentication is disabled.

    • cache

      io.fluxzero.common.caching.Cache cache()
      Returns the cache used by the client to cache aggregates etc.

    • correlationDataProvider

      CorrelationDataProvider correlationDataProvider()
      Returns the provider of correlation data for published messages.

    • serializer

      Serializer serializer()
      Returns the default serializer

    • clock

      Clock clock()
      Returns the clock used by Fluxzero to generate timestamps.

    • identityProvider

      IdentityProvider identityProvider()
      Returns the factory used by Fluxzero to generate identifiers.

    • propertySource

      io.fluxzero.common.application.PropertySource propertySource()
      Returns the PropertySource configured for this Fluxzero instance.

    • taskScheduler

      io.fluxzero.common.TaskScheduler taskScheduler()
      Returns the TaskScheduler of this Fluxzero instance.

    • memoization

      Memoization memoization()
      Returns the memoization store of this Fluxzero instance.

    • configuration

      FluxzeroConfiguration configuration()
      Returns the FluxzeroConfiguration of this Fluxzero instance.

    • executeModelCommit

      default CompletableFuture<Void> executeModelCommit(Message update)
      Executes one model commit without routing it through command handlers.

      This is an infrastructure extension point used by assertAndApply(Object). Custom Fluxzero implementations that support independent models should override it.

      Parameters:
      update - message containing the model update
      Returns:
      completion of the durable model commit

    • commitModelChanges

      default CompletableFuture<Void> commitModelChanges()
      Flushes Model changes already attached to the current handling context. This extension point backs commit() and may be overridden by custom Fluxzero implementations with a different Model pipeline.

    • executeModelCommit

      default CompletableFuture<Void> executeModelCommit(Message update, String modelId, Class<?> modelType)
      Executes one model commit against an explicitly selected persisted model identity. This is the infrastructure extension used by Graph.assertAndApply(Object); custom implementations supporting independent models may override it alongside executeModelCommit(Message).

    • executeModelCommits

      default CompletableFuture<Void> executeModelCommits(List<Message> updates)
      Executes multiple independent model commits without routing them through command handlers. The default implementation preserves compatibility for custom implementations by invoking executeModelCommit(Message) for every update. Implementations may override this to batch transport while retaining separate commit semantics.
      Parameters:
      updates - messages containing independent model updates
      Returns:
      completion after every durable model commit

    • executeStoredModelEvent

      default CompletableFuture<Void> executeStoredModelEvent(Message event)
      Applies an event that was already accepted by its original command flow to independent models. Assertions and apply interceptors are skipped, while regular @Apply methods and durable Model-event storage are preserved. The accepted event is not published again. This infrastructure hook is primarily used by replay and test fixtures.
      Parameters:
      event - previously accepted event to apply
      Returns:
      completion of the durable model commit

    • executeModelAssertions

      default CompletableFuture<Void> executeModelAssertions(Message update)
      Executes model apply interceptors and immediate assertions without applying or committing the update.

      This is an infrastructure extension point used by assertLegal(Object). Custom Fluxzero implementations that support independent models should override it.

      Parameters:
      update - message containing the model update to validate
      Returns:
      completion of the validation-only model evaluation

    • client

      Client client()
      Returns the low level client used by this Fluxzero instance to interface with the Fluxzero Runtime. Of course the returned client may also be a stand-in for the actual service.

    • apply

      default <R> R apply(io.fluxzero.common.ThrowingFunction<Fluxzero,R> function)
      Applies the given function with this Fluxzero set as current threadlocal instance.

    • execute

      default void execute(io.fluxzero.common.ThrowingConsumer<Fluxzero> task)
      Executes the given task with this Fluxzero set as current threadlocal instance.

    • beforeShutdown

      io.fluxzero.common.Registration beforeShutdown(Runnable task)
      Register a task to run before this Fluxzero instance is closed.

    • close

      default void close()
      Closes this Fluxzero instance gracefully.
      Specified by:
      close in interface AutoCloseable

    • close

      void close(boolean silently)
      Closes this Fluxzero instance gracefully. If silently is true, shutdown is done without logging.