Interface Client

All Superinterfaces:
Namespaced<Client>
All Known Implementing Classes:
AbstractClient, LocalClient, WebSocketClient
public interface Client extends Namespaced<Client>
Defines the low-level client contract used by FluxzeroBuilder to construct a Fluxzero instance.

Application developers must provide an implementation of this interface to the FluxzeroBuilder.build(Client) method. This allows for flexible configuration, enabling either an in-memory setup (useful for testing and local development) or a connected (WebSocket-based) client that integrates with the Fluxzero Runtime.

Client Implementations

Common implementations include:

Responsibilities

A Client implementation is responsible for:

Usage

Client client = LocalClient.newInstance();
Fluxzero fluxzero = FluxzeroBuilder.newInstance().build(client);

  • Method Details

    • name

      String name()
      Returns the name of this client as defined in its configuration.

    • id

      String id()
      Returns the unique identifier of this client instance. This id may be randomly generated.

    • applicationId

      String applicationId()
      Returns the application ID under which this client instance is registered.

    • namespace

      String namespace()
      Returns the namespace associated with this client instance.

    • getGatewayClient

      default GatewayClient getGatewayClient(io.fluxzero.common.MessageType messageType)
      Returns a GatewayClient for the given message type using the default topic (typically null).

      For MessageType.DOCUMENT or MessageType.CUSTOM, this method is not supported and will throw an UnsupportedOperationException, as these require a topic.

      Parameters:
      messageType - the type of message gateway
      Returns:
      the associated GatewayClient
      Throws:
      UnsupportedOperationException - if the message type requires a topic

    • getGatewayClient

      GatewayClient getGatewayClient(io.fluxzero.common.MessageType messageType, String topic)
      Returns a GatewayClient for the given message type and topic.
      Parameters:
      messageType - the type of message (e.g. COMMAND, EVENT, etc.)
      topic - the topic to publish messages to (may be null for default)

    • monitorDispatch

      io.fluxzero.common.Registration monitorDispatch(ClientDispatchMonitor monitor, io.fluxzero.common.MessageType... messageTypes)
      Registers a ClientDispatchMonitor to receive hooks and diagnostics when messages of the given MessageTypes are dispatched from this client.
      Parameters:
      monitor - the dispatch monitor to register
      messageTypes - the message types to monitor
      Returns:
      a Registration handle to remove the monitor

    • getTrackingClient

      default TrackingClient getTrackingClient(io.fluxzero.common.MessageType messageType)
      Returns a TrackingClient for the given message type using the default topic.

      For MessageType.DOCUMENT or MessageType.CUSTOM, this method is not supported and will throw an UnsupportedOperationException.

      Parameters:
      messageType - the type of message to track
      Returns:
      the associated TrackingClient
      Throws:
      UnsupportedOperationException - if the message type requires a topic

    • getTrackingClient

      TrackingClient getTrackingClient(io.fluxzero.common.MessageType messageType, String topic)
      Returns a TrackingClient for the given message type and topic.
      Parameters:
      messageType - the type of message to track (e.g. COMMAND, EVENT, QUERY)
      topic - the topic to track messages from (may be null for default)

    • getEventStoreClient

      EventStoreClient getEventStoreClient()
      Returns the EventStoreClient associated with this client for querying event logs.

    • getSchedulingClient

      SchedulingClient getSchedulingClient()
      Returns the SchedulingClient used to interact with the Fluxzero scheduling subsystem.

    • getKeyValueClient

      KeyValueClient getKeyValueClient()
      Returns the KeyValueClient for key-value store interactions.

      This is mostly deprecated and maintained for backward compatibility.

    • getSearchClient

      SearchClient getSearchClient()
      Returns the SearchClient that provides access to document and search APIs.

    • shutDown

      void shutDown()
      Shuts down this client instance, releasing any underlying resources.

      This includes closing websocket sessions, stopping tracking, and executing registered shutdown hooks.

    • prepareShutdown

      default void prepareShutdown()
      Announces controlled shutdown before application callbacks and consumers drain. Implementations may stop liveness monitoring, but must keep transport and other resources available until shutDown(). Repeated calls must be harmless. The default implementation does nothing.

    • beforeShutdown

      io.fluxzero.common.Registration beforeShutdown(Runnable task)
      Registers a shutdown hook that will be called before this client shuts down.
      Parameters:
      task - the action to invoke before shutdown
      Returns:
      a Registration to remove the task

    • unwrap

      default Client unwrap()
      Returns the underlying Client implementation. This is a convenience method to allow clients to explicitly unwrap proxies or decorators.
      Returns:
      the concrete Client instance (often this itself)