Package org.axonframework.messaging.queryhandling.gateway

Interface QueryGateway

All Superinterfaces:
DescribableComponent
All Known Implementing Classes:
DefaultQueryGateway
public interface QueryGateway extends DescribableComponent
Interface towards the Query Handling components of an application.

This interface provides a friendlier API toward the QueryBus.

Since:
3.1.0
Author:
Allard Buijze, Marc Gathier, Milan Savic, Steven van Beelen

  • Method Details

    • query

      <R> CompletableFuture<R> query(Object query, Class<R> responseType, @Nullable ProcessingContext context)
      Sends given query over the QueryBus, expecting a single response with the given responseType from a single source.

      Execution may be asynchronous, depending on the QueryBus implementation.

      The given query is wrapped as the payload of the QueryMessage that is eventually posted on the QueryBus, unless the query already implements Message. In that case, a QueryMessage is constructed from that message's payload and Metadata.

      Type Parameters:
      R - the generic type of the expected response
      Parameters:
      query - the query to be sent
      responseType - a Class describing the desired response type
      context - the processing context, if any, to dispatch the given query in
      Returns:
      a CompletableFuture containing a single query response of type responseType

    • query

      default <R> CompletableFuture<R> query(Object query, Class<R> responseType)
      Sends given query over the QueryBus, expecting a single response with the given responseType from a single source.

      Execution may be asynchronous, depending on the QueryBus implementation.

      The given query is wrapped as the payload of the QueryMessage that is eventually posted on the QueryBus, unless the query already implements Message. In that case, a QueryMessage is constructed from that message's payload and Metadata.

      Type Parameters:
      R - the generic type of the expected response
      Parameters:
      query - the query to be sent
      responseType - a Class describing the desired response type
      Returns:
      a CompletableFuture containing a single query response of type responseType
      See Also:

    • query

      default <R> CompletableFuture<R> query(Object query, Class<R> responseType, Metadata metadata, @Nullable ProcessingContext context)
      Sends given query with the given metadata in the provided context (if available) over the QueryBus, expecting a single response with the given responseType from a single source.

      Execution may be asynchronous, depending on the QueryBus implementation.

      The given query and metadata are wrapped as the payload of the QueryMessage that is eventually posted on the QueryBus, unless the query already implements Message. In that case, a QueryMessage is constructed from that message's payload and Metadata. The provided metadata is attached afterward in this case.

      Implementations must override this method to support attaching the given metadata; the default implementation throws an UnsupportedOperationException.

      Type Parameters:
      R - the generic type of the expected response
      Parameters:
      query - the query to be sent
      responseType - a Class describing the desired response type
      metadata - the metadata to attach to the query
      context - the processing context, if any, to dispatch the given query in
      Returns:
      a CompletableFuture containing a single query response of type responseType
      Since:
      5.3.0

    • queryMany

      <R> CompletableFuture<List<R>> queryMany(Object query, Class<R> responseType, @Nullable ProcessingContext context)
      Sends given query over the QueryBus, expecting multiple responses in the form of responseType from a single source.

      Execution may be asynchronous, depending on the QueryBus implementation.

      The given query is wrapped as the payload of the QueryMessage that is eventually posted on the QueryBus, unless the query already implements Message. In that case, a QueryMessage is constructed from that message's payload and Metadata.

      Type Parameters:
      R - the generic type of the expected response(s)
      Parameters:
      query - the query to be sent
      responseType - a Class describing the desired response type
      context - the processing context, if any, to dispatch the given query in
      Returns:
      a CompletableFuture containing a list of query responses of type responseType

    • queryMany

      default <R> CompletableFuture<List<R>> queryMany(Object query, Class<R> responseType)
      Sends given query over the QueryBus, expecting multiple responses in the form of responseType from a single source.

      Execution may be asynchronous, depending on the QueryBus implementation.

      The given query is wrapped as the payload of the QueryMessage that is eventually posted on the QueryBus, unless the query already implements Message. In that case, a QueryMessage is constructed from that message's payload and Metadata.

      Type Parameters:
      R - the generic type of the expected response(s)
      Parameters:
      query - the query to be sent
      responseType - a Class describing the desired response type
      Returns:
      a CompletableFuture containing a list of query responses of type responseType
      See Also:

    • queryMany

      default <R> CompletableFuture<List<R>> queryMany(Object query, Class<R> responseType, Metadata metadata, @Nullable ProcessingContext context)
      Sends given query with the given metadata in the provided context (if available) over the QueryBus, expecting multiple responses in the form of responseType from a single source.

      Execution may be asynchronous, depending on the QueryBus implementation.

      The given query and metadata are wrapped as the payload of the QueryMessage that is eventually posted on the QueryBus, unless the query already implements Message. In that case, a QueryMessage is constructed from that message's payload and Metadata. The provided metadata is attached afterward in this case.

      Implementations must override this method to support attaching the given metadata; the default implementation throws an UnsupportedOperationException.

      Type Parameters:
      R - the generic type of the expected response(s)
      Parameters:
      query - the query to be sent
      responseType - a Class describing the desired response type
      metadata - the metadata to attach to the query
      context - the processing context, if any, to dispatch the given query in
      Returns:
      a CompletableFuture containing a list of query responses of type responseType
      Since:
      5.3.0

    • streamingQuery

      <R> org.reactivestreams.Publisher<R> streamingQuery(Object query, Class<R> responseType, @Nullable ProcessingContext context)
      Sends given query over the QueryBus, expecting a response as a Publisher of responseType.

      The query is sent once the Publisher is subscribed to. The streaming query allows a client to stream large result sets. Usage of this method requires Project Reactor on the class path.

      The given query is wrapped as the payload of the QueryMessage that is eventually posted on the QueryBus, unless the query already implements Message. In that case, a QueryMessage is constructed from that message's payload and Metadata.

      Publisher is used for backwards compatibility reason, for clients that don't have Project Reactor on class path. Check Reactor Extension for native Flux type and more. Use Flux.from(publisher) to convert to Flux stream.

      Type Parameters:
      R - the generic type of the expected response(s)
      Parameters:
      query - the query to be sent
      responseType - a Class describing the desired response type
      context - the processing context, if any, to dispatch the given query in
      Returns:
      a Publisher streaming the results as dictated by the given responseType

    • streamingQuery

      default <R> org.reactivestreams.Publisher<R> streamingQuery(Object query, Class<R> responseType)
      Sends given query over the QueryBus, expecting a response as a Publisher of responseType.

      The query is sent once the Publisher is subscribed to. The streaming query allows a client to stream large result sets. Usage of this method requires Project Reactor on the class path.

      The given query is wrapped as the payload of the QueryMessage that is eventually posted on the QueryBus, unless the query already implements Message. In that case, a QueryMessage is constructed from that message's payload and Metadata.

      Publisher is used for backwards compatibility reason, for clients that don't have Project Reactor on class path. Check Reactor Extension for native Flux type and more. Use Flux.from(publisher) to convert to Flux stream.

      Type Parameters:
      R - the generic type of the expected response(s)
      Parameters:
      query - the query to be sent
      responseType - a Class describing the desired response type
      Returns:
      a Publisher streaming the results as dictated by the given responseType
      See Also:

    • streamingQuery

      default <R> org.reactivestreams.Publisher<R> streamingQuery(Object query, Class<R> responseType, Metadata metadata, @Nullable ProcessingContext context)
      Sends given query with the given metadata in the provided context (if available) over the QueryBus, expecting a response as a Publisher of responseType.

      The query is sent once the Publisher is subscribed to. See streamingQuery(Object, Class) for the streaming semantics and Project Reactor requirements.

      The given query and metadata are wrapped as the payload of the QueryMessage that is eventually posted on the QueryBus, unless the query already implements Message. In that case, a QueryMessage is constructed from that message's payload and Metadata. The provided metadata is attached afterward in this case.

      Implementations must override this method to support attaching the given metadata; the default implementation throws an UnsupportedOperationException.

      Type Parameters:
      R - the generic type of the expected response(s)
      Parameters:
      query - the query to be sent
      responseType - a Class describing the desired response type
      metadata - the metadata to attach to the query
      context - the processing context, if any, to dispatch the given query in
      Returns:
      a Publisher streaming the results as dictated by the given responseType
      Since:
      5.3.0

    • subscriptionQuery

      default <R> org.reactivestreams.Publisher<R> subscriptionQuery(Object query, Class<R> responseType, @Nullable ProcessingContext context)
      Sends given query over the QueryBus as a subscription query, combining the initial result and emitted update as a Publisher of the given responseType.

      The query is sent once the Publisher is subscribed to. Furthermore, updates are received at the moment the query is sent, and until it is cancelled by the caller or closed by the emitting side.

      The given query is wrapped as the payload of the QueryMessage that is eventually posted on the QueryBus, unless the query already implements Message. In that case, a QueryMessage is constructed from that message's payload and Metadata.

      Note that any null results, on the initial result or the update, will be filtered out by the gateway. If you require the null to be returned for the initial and update results, we suggest using the QueryBus instead.

      The returned Publisher must be subscribed to and consumed from before the buffer fills up. Once the buffer is full, any attempt to add an update will complete the stream with an exception.

      Type Parameters:
      R - the type of all the responses
      Parameters:
      query - the query to be sent
      responseType - the response type returned by this query as the initial result and the update
      context - the processing context, if any, to dispatch the given query in
      Returns:
      a Publisher streaming the results as dictated by the given responseType

    • subscriptionQuery

      default <R> org.reactivestreams.Publisher<R> subscriptionQuery(Object query, Class<R> responseType)
      Sends given query over the QueryBus as a subscription query, combining the initial result and emitted update as a Publisher of the given responseType.

      The query is sent once the Publisher is subscribed to. Furthermore, updates are received at the moment the query is sent, and until it is cancelled by the caller or closed by the emitting side.

      The given query is wrapped as the payload of the QueryMessage that is eventually posted on the QueryBus, unless the query already implements Message. In that case, a QueryMessage is constructed from that message's payload and Metadata.

      Note that any null results, on the initial result or the update, will be filtered out by the gateway. If you require the null to be returned for the initial and update results, we suggest using the QueryBus instead.

      The returned Publisher must be subscribed to and consumed from before the buffer fills up. Once the buffer is full, any attempt to add an update will complete the stream with an exception.

      Type Parameters:
      R - the type of all the responses
      Parameters:
      query - the query to be sent
      responseType - the response type returned by this query as the initial result and the update
      Returns:
      a Publisher streaming the results as dictated by the given responseType

    • subscriptionQuery

      <R> org.reactivestreams.Publisher<R> subscriptionQuery(Object query, Class<R> responseType, @Nullable ProcessingContext context, int updateBufferSize)
      Sends given query over the QueryBus as a subscription query, combining the initial result and emitted update as a Publisher of the given responseType.

      The query is sent once the Publisher is subscribed to. Furthermore, updates are received at the moment the query is sent, and until it is cancelled by the caller or closed by the emitting side.

      The given query is wrapped as the payload of the QueryMessage that is eventually posted on the QueryBus, unless the query already implements Message. In that case, a QueryMessage is constructed from that message's payload and Metadata.

      Note that any null results, on the initial result or the update, will be filtered out by the gateway. If you require the null to be returned for the initial and update results, we suggest using the QueryBus instead.

      The returned Publisher must be subscribed to and consumed from before the buffer fills up. Once the buffer is full, any attempt to add an update will complete the stream with an exception.

      Type Parameters:
      R - the type of all the responses
      Parameters:
      query - the query to be sent
      responseType - the response type returned by this query as the initial result and the update
      context - the processing context, if any, to dispatch the given query in
      updateBufferSize - the size of buffer which accumulates updates before a subscription to the Flux is made
      Returns:
      a Publisher streaming the results as dictated by the given responseType

    • subscriptionQuery

      default <R> org.reactivestreams.Publisher<R> subscriptionQuery(Object query, Class<R> responseType, Metadata metadata, @Nullable ProcessingContext context, int updateBufferSize)
      Sends given query with the given metadata over the QueryBus as a subscription query, combining the initial result and emitted update as a Publisher of the given responseType.

      The query is sent once the Publisher is subscribed to. Furthermore, updates are received at the moment the query is sent, and until it is cancelled by the caller or closed by the emitting side.

      The given query and metadata are wrapped as the payload of the QueryMessage that is eventually posted on the QueryBus, unless the query already implements Message. In that case, a QueryMessage is constructed from that message's payload and Metadata. The provided metadata is attached afterward in this case.

      Implementations must override this method to support attaching the given metadata; the default implementation throws an UnsupportedOperationException.

      Note that any null results, on the initial result or the update, will be filtered out by the gateway. If you require the null to be returned for the initial and update results, we suggest using the QueryBus instead.

      The returned Publisher must be subscribed to and consumed from before the buffer fills up. Once the buffer is full, any attempt to add an update will complete the stream with an exception.

      Type Parameters:
      R - the type of all the responses
      Parameters:
      query - the query to be sent
      responseType - the response type returned by this query as the initial result and the update
      metadata - the metadata to attach to the query
      context - the processing context, if any, to dispatch the given query in
      updateBufferSize - the size of buffer which accumulates updates before a subscription to the Flux is made
      Returns:
      a Publisher streaming the results as dictated by the given responseType
      Since:
      5.3.0

    • subscriptionQuery

      default <R> org.reactivestreams.Publisher<R> subscriptionQuery(Object query, Class<R> responseType, Function<QueryResponseMessage,R> mapper, @Nullable ProcessingContext context)
      Sends given query over the QueryBus and returns a Publisher supplying the initial update followed by the update. The given mapper is used to map the QueryResponseMessage to the desired object type. To distinguish between the initial result and the update, the given mapper can check whether the given responseMessage is an instance of SubscriptionQueryUpdateMessage. In that case the message is considered an update, otherwise it is considered the initial result.

      The query is sent upon invocation of this method. Furthermore, updates are received at the moment the query is sent, and until the subscription to the Publisher is canceled by the caller or closed by the emitting side.

      The given query is wrapped as the payload of the QueryMessage that is eventually posted on the QueryBus, unless the query already implements Message. In that case, a QueryMessage is constructed from that message's payload and Metadata.

      Note that any null results, on the initial result or the update, will be filtered out by the gateway. If you require the null to be returned for the initial and update results, we suggest using the QueryBus instead.

      The returned Publisher must be subscribed to and consumed from before the buffer fills up. Once the buffer is full, any attempt to add an update will complete the stream with an exception. To control the buffer size, use subscriptionQuery(Object, Class, Function, ProcessingContext, int).

      Type Parameters:
      R - the type payload to map the responses to
      Parameters:
      query - the query to be sent
      responseType - the response type returned by this query as the initial result
      mapper - a Function that maps the QueryResponseMessage to the desired response
      context - the processing context, if any, to dispatch the given query in
      Returns:
      a Publisher which can be used to cancel receiving update
      See Also:

    • subscriptionQuery

      default <R> org.reactivestreams.Publisher<R> subscriptionQuery(Object query, Class<R> responseType, Function<QueryResponseMessage,R> mapper)
      Sends given query over the QueryBus and returns a Publisher supplying the initial update followed by the update. The given mapper is used to map the QueryResponseMessage to the desired object type. To distinguish between the initial result and the update, the given mapper can check whether the given responseMessage is an instance of SubscriptionQueryUpdateMessage. In that case the message is considered an update, otherwise it is considered the initial result.

      The query is sent upon invocation of this method. Furthermore, updates are received at the moment the query is sent, and until the subscription to the Publisher is canceled by the caller or closed by the emitting side.

      The given query is wrapped as the payload of the QueryMessage that is eventually posted on the QueryBus, unless the query already implements Message. In that case, a QueryMessage is constructed from that message's payload and Metadata.

      Note that any null results, on the initial result or the update, will be filtered out by the gateway. If you require the null to be returned for the initial and update results, we suggest using the QueryBus instead.

      The returned Publisher must be subscribed to and consumed from before the buffer fills up. Once the buffer is full, any attempt to add an update will complete the stream with an exception. To control the buffer size, use subscriptionQuery(Object, Class, Function, ProcessingContext, int).

      Type Parameters:
      R - the type payload to map the responses to
      Parameters:
      query - the query to be sent
      responseType - the response type returned by this query as the initial result
      mapper - a Function that maps the QueryResponseMessage to the desired response
      Returns:
      a Publisher which can be used to cancel receiving update
      See Also:

    • subscriptionQuery

      default <R> org.reactivestreams.Publisher<R> subscriptionQuery(Object query, Class<R> responseType, int updateBufferSize)
      Sends given query over the QueryBus and returns a Publisher supplying the initial update followed by the update. The given mapper is used to map the QueryResponseMessage to the desired object type. To distinguish between the initial result and the update, the given mapper can check whether the given responseMessage is an instance of SubscriptionQueryUpdateMessage. In that case the message is considered an update, otherwise it is considered the initial result.

      The query is sent upon invocation of this method. Furthermore, updates are received at the moment the query is sent, and until the subscription to the Publisher is canceled by the caller or closed by the emitting side.

      The given query is wrapped as the payload of the QueryMessage that is eventually posted on the QueryBus, unless the query already implements Message. In that case, a QueryMessage is constructed from that message's payload and Metadata.

      Note that any null results, on the initial result or the update, will be filtered out by the gateway. If you require the null to be returned for the initial and update results, we suggest using the QueryBus instead.

      Type Parameters:
      R - the type payload to map the responses to
      Parameters:
      query - the query to be sent
      responseType - the response type returned by this query as the initial result
      updateBufferSize - the size of the buffer which accumulates updates to be processed
      Returns:
      a Publisher which can be used to cancel receiving update
      See Also:

    • subscriptionQuery

      <R> org.reactivestreams.Publisher<R> subscriptionQuery(Object query, Class<R> responseType, Function<QueryResponseMessage,R> mapper, @Nullable ProcessingContext context, int updateBufferSize)
      Sends given query over the QueryBus and returns a Publisher supplying the initial update followed by the update. The given mapper is used to map the QueryResponseMessage to the desired object type. To distinguish between the initial result and the update, the given mapper can check whether the given responseMessage is an instance of SubscriptionQueryUpdateMessage. In that case the message is considered an update, otherwise it is considered the initial result.

      The query is sent upon invocation of this method. Furthermore, updates are received at the moment the query is sent, and until the subscription to the Publisher is canceled by the caller or closed by the emitting side.

      The given query is wrapped as the payload of the QueryMessage that is eventually posted on the QueryBus, unless the query already implements Message. In that case, a QueryMessage is constructed from that message's payload and Metadata.

      Note that any null results, on the initial result or the update, will be filtered out by the gateway. If you require the null to be returned for the initial and update results, we suggest using the QueryBus instead.

      Type Parameters:
      R - the type payload to map the responses to
      Parameters:
      query - the query to be sent
      responseType - the response type returned by this query as the initial result
      mapper - a Function that maps the QueryResponseMessage to the desired response; messages for which the mapper returns a null value are filtered out
      context - the processing context, if any, to dispatch the given query in
      updateBufferSize - the size of the buffer which accumulates updates to be processed
      Returns:
      a Publisher which can be used to cancel receiving update
      See Also:

    • subscriptionQuery

      default <R> org.reactivestreams.Publisher<R> subscriptionQuery(Object query, Class<R> responseType, Function<QueryResponseMessage,R> mapper, int updateBufferSize)
      Sends given query over the QueryBus and returns a Publisher supplying the initial update followed by the update. The given mapper is used to map the QueryResponseMessage to the desired object type. To distinguish between the initial result and the update, the given mapper can check whether the given responseMessage is an instance of SubscriptionQueryUpdateMessage. In that case the message is considered an update, otherwise it is considered the initial result.

      The query is sent upon invocation of this method. Furthermore, updates are received at the moment the query is sent, and until the subscription to the Publisher is canceled by the caller or closed by the emitting side.

      The given query is wrapped as the payload of the QueryMessage that is eventually posted on the QueryBus, unless the query already implements Message. In that case, a QueryMessage is constructed from that message's payload and Metadata.

      Note that any null results, on the initial result or the update, will be filtered out by the gateway. If you require the null to be returned for the initial and update results, we suggest using the QueryBus instead.

      Type Parameters:
      R - the type payload to map the responses to
      Parameters:
      query - the query to be sent
      responseType - the response type returned by this query as the initial result
      mapper - a Function that maps the QueryResponseMessage to the desired response; messages for which the mapper returns a null value are filtered out
      updateBufferSize - the size of the buffer which accumulates updates to be processed
      Returns:
      a Publisher which can be used to cancel receiving update
      See Also: