Interface QueryGateway

All Superinterfaces:
HasLocalHandlers, Namespaced<QueryGateway>
All Known Implementing Classes:
DefaultQueryGateway
public interface QueryGateway extends Namespaced<QueryGateway>, HasLocalHandlers
Gateway interface for dispatching queries and receiving responses in Fluxzero.

The QueryGateway provides a high-level API for submitting queries and retrieving results, either asynchronously or synchronously. It supports rich metadata and integrates with both local and remote query handlers.

Queries can be sent as raw payloads, Message objects, or Request wrappers for typed responses. This interface also supports registration of local handlers via HasLocalHandlers.registerHandler(Object).

For message types that are queries, the MessageType.QUERY enum is typically used.

See Also:

  • Method Details

    • send

      <R> CompletableFuture<R> send(Object query)
      Sends the given query asynchronously and returns a future representing the result.

      If the query is a Message, it is dispatched as-is. Otherwise, it is wrapped in a new message.

      Type Parameters:
      R - the expected type of the result
      Parameters:
      query - the query object
      Returns:
      a CompletableFuture with the result

    • send

      <R> CompletableFuture<R> send(Object payload, io.fluxzero.common.api.Metadata metadata)
      Sends the given query along with metadata asynchronously and returns a future representing the result.
      Type Parameters:
      R - the expected result type
      Parameters:
      payload - the query payload
      metadata - additional metadata to attach to the message
      Returns:
      a CompletableFuture containing the query result

    • sendForMessage

      CompletableFuture<Message> sendForMessage(Message message)
      Sends the given Message and returns a future representing the resulting message. This method gives access to the full Message returned by the query handler.
      Parameters:
      message - the message representing the query
      Returns:
      a CompletableFuture with the response message

    • send

      <R> List<CompletableFuture<R>> send(Object... messages)
      Sends multiple queries asynchronously and returns a list of futures, one for each result.
      Type Parameters:
      R - the expected result type for each query
      Parameters:
      messages - one or more query objects or messages
      Returns:
      a list of CompletableFutures for each query result

    • sendForMessages

      List<CompletableFuture<Message>> sendForMessages(Message... messages)
      Sends multiple query Messages and returns a list of futures for the raw responses.
      Parameters:
      messages - one or more messages representing queries
      Returns:
      a list of CompletableFutures containing the result messages

    • sendAndWait

      <R> R sendAndWait(Object query)
      Sends the given query and waits for the result, blocking the current thread.
      Type Parameters:
      R - the expected result type
      Parameters:
      query - the query object
      Returns:
      the result of the query

    • sendAndWait

      <R> R sendAndWait(Object payload, io.fluxzero.common.api.Metadata metadata)
      Sends the given query and metadata, then waits for the result.
      Type Parameters:
      R - the expected result type
      Parameters:
      payload - the query payload
      metadata - additional metadata to attach to the query
      Returns:
      the result of the query

    • send

      <R> CompletableFuture<R> send(Request<R> query)
      Sends a typed Request query and returns a future representing the result.
      Type Parameters:
      R - the expected result type
      Parameters:
      query - the Request query
      Returns:
      a CompletableFuture containing the result

    • send

      <R> CompletableFuture<R> send(Request<R> payload, io.fluxzero.common.api.Metadata metadata)
      Sends a typed Request query with additional metadata and returns a future with the result.
      Type Parameters:
      R - the expected result type
      Parameters:
      payload - the Request payload
      metadata - metadata to attach to the request
      Returns:
      a CompletableFuture with the result

    • sendAndWait

      <R> R sendAndWait(Request<R> query)
      Sends a typed Request query and waits for the result.
      Type Parameters:
      R - the expected result type
      Parameters:
      query - the Request query
      Returns:
      the result of the query

    • sendAndWait

      <R> R sendAndWait(Request<R> payload, io.fluxzero.common.api.Metadata metadata)
      Sends a typed Request query with metadata and waits for the result.
      Type Parameters:
      R - the expected result type
      Parameters:
      payload - the Request payload
      metadata - additional metadata to attach to the query
      Returns:
      the result of the query

    • close

      void close()
      Gracefully shuts down this gateway and releases any held resources.

    • send

      default <R> CompletableFuture<R> send(Object payload, io.fluxzero.common.api.Metadata metadata, io.fluxzero.common.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, io.fluxzero.common.api.Metadata metadata, io.fluxzero.common.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, io.fluxzero.common.api.Metadata metadata, io.fluxzero.common.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, io.fluxzero.common.api.Metadata metadata, io.fluxzero.common.Guarantee guarantee)
      Sends a typed request with a per-call publication guarantee and waits for its business response.

    • sendForMessages

      default List<CompletableFuture<Message>> sendForMessages(io.fluxzero.common.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.