Interface GenericGateway

All Superinterfaces:
AutoCloseable, HasLocalHandlers, Namespaced<GenericGateway>
All Known Implementing Classes:
DefaultGenericGateway
public interface GenericGateway extends Namespaced<GenericGateway>, HasLocalHandlers, AutoCloseable
A generic message gateway for publication of messages in Fluxzero.

The GenericGateway provides a uniform interface to send and receive messages over any standard or user-defined topic, enabling extensibility beyond the default types such as commands, queries, events, and errors.

This interface supports asynchronous and synchronous message dispatching, both with and without awaiting a result. It also includes support for delivery guarantees and local handler registration.

Typical usage includes:

  • Custom message flows that don’t fit standard message types
  • Internal APIs that benefit from topic-based routing
  • Feature-specific messaging with isolated topics

Obtaining a Gateway

Use Fluxzero.customGateway(String) to create or retrieve a GenericGateway for a given topic: 
GenericGateway myGateway = Fluxzero.customGateway("myTopic");
See Also:

  • Method Details

    • sendAndForget

      default void sendAndForget(Object message)
      Sends a message with the application's Guarantee.DEFAULT without waiting for a result or remote acknowledgement. A participating tracking completion scope awaits delivery before committing its consumer position; see Consumer.awaitOutgoingWrites() for opt-outs and streaming boundaries. Outside tracking, use a future-returning overload to observe delivery confirmation or asynchronous failures.

    • sendAndForget

      default void sendAndForget(Object payload, Metadata metadata)
      Sends a message with custom payload and metadata asynchronously.

    • sendAndForget

      default void sendAndForget(Object payload, Metadata metadata, Guarantee guarantee)
      Sends a message with payload, metadata, and delivery guarantee asynchronously.

    • sendAndForget

      default CompletableFuture<Void> sendAndForget(Message message, Guarantee guarantee)
      Sends a Message asynchronously with a given guarantee.

    • sendAndForget

      default void sendAndForget(Object... messages)
      Sends multiple messages asynchronously with Guarantee.DEFAULT.

    • sendAndForget

      default CompletableFuture<Void> sendAndForget(Guarantee guarantee, Object... messages)
      Sends multiple messages asynchronously with a specified delivery guarantee.

    • sendAndForget

      CompletableFuture<Void> sendAndForget(Guarantee guarantee, Message... messages)
      Sends multiple Message objects with a guarantee.

    • sendAndForget

      CompletableFuture<Void> sendAndForget(Guarantee guarantee, UnaryOperator<SerializedMessage> interceptor, Message... messages)
      Sends multiple Message objects with a guarantee.

      Before the messages are appended to the message log in Fluxzero, they can be inspected, blocked or modified using the given interceptor.

    • send

      default <R> CompletableFuture<R> send(Message message)
      Sends a Message and returns a future that completes with its response payload.

    • send

      default <R> CompletableFuture<R> send(Object message)
      Sends a message (raw object or Request) and returns a future with its response.

    • send

      default <R> CompletableFuture<R> send(Request<R> message)
      Sends a Request message and returns a future with its typed response.

    • send

      default <R> CompletableFuture<R> send(Object payload, Metadata metadata)
      Sends a message with custom metadata and returns a future with its response.

    • send

      default <R> CompletableFuture<R> send(Request<R> payload, Metadata metadata)
      Sends a Request with metadata and returns a future with its response.

    • sendForMessage

      default CompletableFuture<Message> sendForMessage(Message message)
      Sends a single Message and returns a future that resolves to the complete Message response.

    • sendForMessage

      CompletableFuture<Message> sendForMessage(Message message, Duration timeout)
      Sends a single request message with the given effective timeout.

      The effective timeout is used for the returned future and is propagated as request metadata so tracking handlers can skip stale indexed requests before invocation. If timeout is null, the gateway falls back to timeout metadata already present on the message, then @Timeout on the payload class, and finally the request handler default. A negative timeout disables timeout handling for this request.

      Parameters:
      message - the message to send
      timeout - the timeout for this request; null uses the gateway/request handler defaults
      Returns:
      a future that completes with the response message

    • send

      default <R> List<CompletableFuture<R>> send(Object... messages)
      Sends multiple messages and returns a list of futures with their payload responses.

    • sendForMessages

      List<CompletableFuture<Message>> sendForMessages(Message... messages)
      Sends multiple messages and returns futures for their full Message responses.

    • sendAndWait

      default <R> R sendAndWait(Object message)
      Sends a message and blocks until a response is received.

    • sendAndWait

      default <R> R sendAndWait(Request<R> message)
      Sends a Request and blocks until a response is received.

    • sendAndWait

      default <R> R sendAndWait(Object payload, Metadata metadata)
      Sends a message with metadata and blocks for a response.

    • sendAndWait

      default <R> R sendAndWait(Request<R> payload, Metadata metadata)
      Sends a Request with metadata and blocks for a response.

    • sendAndWait

      <R> R sendAndWait(Message message)
      Sends a message and blocks for a result with a configurable timeout.

      Timeout can be customized using @Timeout on the payload class.

    • setRetentionTime

      default void setRetentionTime(Duration duration)
      Set a new retention duration for the underlying gateway's message log.

      The retention setting determines how long messages in this log are retained by the system, after which they may be evicted or deleted depending on the platform policy.

      Parameters:
      duration - the new retention duration

    • setRetentionTime

      CompletableFuture<Void> setRetentionTime(Duration duration, Guarantee guarantee)
      Set a new retention duration for the underlying gateway's message log.

      The retention setting determines how long messages in this log are retained by the system, after which they may be evicted or deleted depending on the platform policy.

      Parameters:
      duration - the new retention duration
      guarantee - the delivery guarantee to apply to the update operation
      Returns:
      a CompletableFuture that completes according to the selected delivery guarantee

    • truncate

      default CompletableFuture<Void> truncate()
      Truncates this gateway's message log and clears associated tracking positions using Guarantee.DEFAULT.
      Returns:
      a CompletableFuture that completes according to the selected delivery guarantee

    • truncate

      CompletableFuture<Void> truncate(Guarantee guarantee)
      Truncates this gateway's message log and clears associated tracking positions.
      Parameters:
      guarantee - the delivery guarantee to apply to the truncate operation
      Returns:
      a CompletableFuture that completes according to the selected delivery guarantee

    • close

      void close()
      Closes this gateway and releases any underlying resources.
      Specified by:
      close in interface AutoCloseable

    • send

      default <R> CompletableFuture<R> send(Object payload, Metadata metadata, Guarantee guarantee)
      Sends a request with the given publication guarantee. The future represents its business response. Guarantee.DEFAULT uses fluxzero.publishing.defaultGuarantee, with the SDK major-version request default when unconfigured. Guarantee.NONE, Guarantee.SENT and Guarantee.STORED override publication for this call only; the business result is still awaited.
      Type Parameters:
      R - response payload type
      Parameters:
      payload - request payload
      metadata - request metadata; use Metadata.empty() when none is needed
      guarantee - request publication guarantee
      Returns:
      the business response future

    • send

      default <R> CompletableFuture<R> send(Request<R> payload, Metadata metadata, Guarantee guarantee)
      Sends a typed request with a per-call publication guarantee and returns its business response future.

    • sendAndWait

      default <R> R sendAndWait(Object payload, Metadata metadata, Guarantee guarantee)
      Sends a request with a per-call publication guarantee and waits for its business response. Storage acknowledgment does not replace or delay an already available business response.

    • sendAndWait

      default <R> R sendAndWait(Request<R> payload, Metadata metadata, Guarantee guarantee)
      Sends a typed request with a per-call publication guarantee and waits for its business response.

    • sendForMessages

      default List<CompletableFuture<Message>> sendForMessages(Guarantee guarantee, Message... messages)
      Sends full request messages with one publication guarantee and returns business response futures in input order. Custom gateways retain their existing batch behavior for DEFAULT; unsupported explicit guarantees fail.

    • sendForMessage

      default CompletableFuture<Message> sendForMessage(Message message, Duration timeout, Guarantee guarantee)
      Sends a full request with a per-call publication guarantee and effective timeout. Timeout interpretation is identical to sendForMessage(Message, Duration). Custom gateways retain their existing timeout behavior for DEFAULT; unsupported explicit guarantees fail.