Package io.fluxcapacitor.javaclient

Interface FluxCapacitor

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
DefaultFluxCapacitor
public interface FluxCapacitor extends AutoCloseable
High-level client for Flux Capacitor. If you are using anything other than this to interact with the service at runtime you're probably doing it wrong.

To start handling messages build an instance of this API and invoke registerHandlers(java.lang.Object...).

Once you are handling messages you can simply use the static methods provided (e.g. to publish messages etc). In those cases it is not necessary to inject an instance of this API. This minimizes the need for dependencies in your functional classes and maximally cashes in on location transparency.

To build an instance of this client check out DefaultFluxCapacitor.

  • Field Details

    • applicationInstance

      static final AtomicReference<FluxCapacitor> applicationInstance
      Flux Capacitor 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 FluxCapacitor instance which will be the case for nearly all applications. On application startup simply fill this application instance.

    • instance

      static final ThreadLocal<FluxCapacitor> instance
      Flux Capacitor instance bound to the current thread. Normally there's only one FluxCapacitor client per application. Before messages are passed to message handlers the FluxCapacitor client binds itself to this field. By doing so message handlers can interact with Flux Capacitor without injecting any dependencies.

  • Method Details

    • get

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

    • getOptionally

      static Optional<FluxCapacitor> getOptionally()
      Returns the FluxCapacitor 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 FluxCapacitor instance (obtained via getOptionally()). If there is no current instance the system's UTC clock is returned.

    • generateId

      static String generateId()
      Gets the IdentityProvider of the current FluxCapacitor to generate a unique identifier. If there is no current FluxCapacitor instance a new UUID is generated.

    • currentIdentityProvider

      static IdentityProvider currentIdentityProvider()
      Fetches the IdentityProvider of the current FluxCapacitor. If there is no current FluxCapacitor 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 that the published event will not be available for event sourcing as it is does not belong to any aggregate.

      See Also:

    • publishEvent

      static void publishEvent(Object payload, Metadata metadata)
      Publishes an event with given payload and metadata.
      See Also:

    • sendAndForgetCommand

      static void sendAndForgetCommand(Object command)
      Sends the given command and don'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:

    • sendAndForgetCommand

      static void sendAndForgetCommand(Object payload, 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, Metadata metadata, 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(Object payload, 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(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(Object payload, Metadata metadata)
      Sends a command with given payload and metadata and returns a future that will be completed with the command's result.

    • 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(Object payload, Metadata metadata)
      Sends a query with given payload and metadata and returns a future that will be completed with the query's result.

    • 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(Object payload, Metadata metadata)
      Sends a query with given payload and metadata and returns the query's result.

    • schedule

      static void schedule(Object schedule, String 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.

    • 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, 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> AggregateRoot<T> loadAggregate(String 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 replayed back to the event currently being handled. Otherwise, the most recent state of the aggregate is loaded.

      See Also:

    • loadAggregateFor

      static <T> AggregateRoot<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 replayed back to the event currently being handled. Otherwise, the most recent state of the aggregate is loaded.

      See Also:

    • loadAggregateFor

      static <T> AggregateRoot<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 replayed 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. no such aggregate exists an empty aggregate root is returned of type Object. In case multiple entities are associated with the given entityId the most recent entity is returned.

    • loadEntityValue

      static <T> Optional<T> loadEntityValue(String 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 an empty optional is returned.

    • applyEvents

      static void applyEvents(String aggregateId, Object... events)
      Convenience method to apply the given events to the aggregate with id aggregateId without loading the aggregate. Events may be Message instances or event message payloads.

    • index

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

    • index

      static void index(Object object, String id, String collection, @Nullable Instant timestamp)
      Index given object for search. This method returns once the object is stored.
      See Also:

    • index

      static void index(Object object, String id, String collection, @Nullable Instant timestamp, @Nullable Instant end)
      Index given object for search. This method returns once the object is stored.
      See Also:

    • index

      static <T> void index(Collection<? extends T> objects, String 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:

    • search

      static Search search(String... collections)
      Search the given collections for documents.

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

    • search

      static Search search(String collection)
      Search the given collection for documents.

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

    • registerHandlers

      default 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 Flux Capacitor service. 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 Registration registerHandlers(List<?> handlers)
      Registers given handlers and initiates message tracking.
      See Also:

    • withClock

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

    • withIdentityProvider

      void withIdentityProvider(IdentityProvider identityProvider)
      Have Flux Capacitor use the given IdentityProvider when generating ids, e.g. when creating a Message.

    • aggregateRepository

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

    • eventStore

      EventStore eventStore()
      Returns the event store client.

    • scheduler

      Scheduler scheduler()
      Returns the message scheduling client.

    • 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.

    • tracking

      Tracking tracking(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 Flux Capacitor.

    • documentStore

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

    • userProvider

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

    • cache

      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 Flux Capacitor to generate timestamps.

    • identityProvider

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

    • client

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

    • apply

      default <R> R apply(Function<FluxCapacitor,R> function)
      Applies the given function with this Flux Capacitor set as current threadlocal instance.

    • execute

      default void execute(Consumer<FluxCapacitor> task)
      Executes the given task with this Flux Capacitor set as current threadlocal instance.

    • beforeShutdown

      Registration beforeShutdown(Runnable task)
      Register a task to run before this Flux Capacitor instance is closed.

    • close

      void close()
      Specified by:
      close in interface AutoCloseable