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 Detail

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

      • get

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

      • 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:
        if you're interested in publishing events that belong to an aggregate.

      • publishEvent

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

      • 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:
        to send a command and inspect its result

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

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

      • 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:
        for more info on how to configure your application using Spring, for more info on local handlers.

      • registerHandlers

        default Registration registerHandlers​(List<?> handlers)
        Registers given handlers and initiates message tracking.
        See Also:
        for more info

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

      • keyValueStore

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

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

      • tracking

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

      • cache

        Cache cache()
        Returns the cache used by the client to cache aggregates etc.

      • serializer

        Serializer serializer()
        Returns the default serializer

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

      • execute

        default <R> R execute​(Function<FluxCapacitor,​R> 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.