org.axonframework.queryhandling

Interface QueryBus

All Superinterfaces:

MessageDispatchInterceptorSupport<QueryMessage<?,?>>, MessageHandlerInterceptorSupport<QueryMessage<?,?>>

All Known Implementing Classes:

AxonServerQueryBus, SimpleQueryBus

public interface QueryBus
extends MessageHandlerInterceptorSupport<QueryMessage<?,?>>, MessageDispatchInterceptorSupport<QueryMessage<?,?>>

The mechanism that dispatches Query objects to their appropriate QueryHandlers. QueryHandlers can subscribe and un-subscribe to specific queries (identified by their QueryMessage.getQueryName() and QueryMessage.getResponseType() on the query bus. There may be multiple handlers for each combination of queryName/responseType.

Since:

3.1

Author:

Marc Gathier, Allard Buijze

Method Summary

Modifier and Type	Method and Description
<Q,R> CompletableFuture<QueryResponseMessage<R>>	query(QueryMessage<Q,R> query) Dispatch the given query to a single QueryHandler subscribed to the given query's queryName and responseType.
QueryUpdateEmitter	queryUpdateEmitter() Gets the QueryUpdateEmitter associated with this QueryBus.
<Q,R> Stream<QueryResponseMessage<R>>	scatterGather(QueryMessage<Q,R> query, long timeout, TimeUnit unit) Dispatch the given query to all QueryHandlers subscribed to the given query's queryName/responseType.
default <Q,R> org.reactivestreams.Publisher<QueryResponseMessage<R>>	streamingQuery(StreamingQueryMessage<Q,R> query) Builds a Publisher of responses to the given query.
<R> Registration	subscribe(String queryName, Type responseType, MessageHandler<? super QueryMessage<?,R>> handler) Subscribe the given handler to queries with the given queryName and responseType.
default <Q,I,U> SubscriptionQueryResult<QueryResponseMessage<I>,SubscriptionQueryUpdateMessage<U>>	subscriptionQuery(SubscriptionQueryMessage<Q,I,U> query) Dispatch the given query to a single QueryHandler subscribed to the given query's queryName/initialResponseType/updateResponseType.
default <Q,I,U> SubscriptionQueryResult<QueryResponseMessage<I>,SubscriptionQueryUpdateMessage<U>>	subscriptionQuery(SubscriptionQueryMessage<Q,I,U> query, int updateBufferSize) Dispatch the given query to a single QueryHandler subscribed to the given query's queryName/initialResponseType/updateResponseType.
default <Q,I,U> SubscriptionQueryResult<QueryResponseMessage<I>,SubscriptionQueryUpdateMessage<U>>	subscriptionQuery(SubscriptionQueryMessage<Q,I,U> query, SubscriptionQueryBackpressure backpressure, int updateBufferSize) Deprecated. in favour of using {subscriptionQuery(SubscriptionQueryMessage, int)}

Methods inherited from interface org.axonframework.messaging.MessageHandlerInterceptorSupport

registerHandlerInterceptor

Methods inherited from interface org.axonframework.messaging.MessageDispatchInterceptorSupport

registerDispatchInterceptor

Method Detail

subscribe

<R> Registration subscribe(@Nonnull
                           String queryName,
                           @Nonnull
                           Type responseType,
                           @Nonnull
                           MessageHandler<? super QueryMessage<?,R>> handler)

Subscribe the given handler to queries with the given queryName and responseType. Multiple handlers may subscribe to the same combination of queryName/responseType.

Parameters:

queryName - the name of the query request to subscribe

responseType - the type of response the subscribed component answers with

handler - a handler that implements the query

Returns:

a handle to un-subscribe the query handler

query

<Q,R> CompletableFuture<QueryResponseMessage<R>> query(@Nonnull
                                                       QueryMessage<Q,R> query)

Dispatch the given query to a single QueryHandler subscribed to the given query's queryName and responseType. This method returns all values returned by the Query Handler as a Collection. This may or may not be the exact collection as defined in the Query Handler.

If the Query Handler defines a single return object (i.e. not a collection or array), that object is returned as the sole entry in a singleton collection.

When no handlers are available that can answer the given query, the returned CompletableFuture will be completed with a NoHandlerForQueryException.

Type Parameters:

Q - the payload type of the query

R - the response type of the query

Parameters:

query - the query

Returns:

a CompletableFuture that resolves when the response is available

streamingQuery

default <Q,R> org.reactivestreams.Publisher<QueryResponseMessage<R>> streamingQuery(StreamingQueryMessage<Q,R> query)

Builds a Publisher of responses to the given query. The actual query is not dispatched until there is a subscription to the result. The query is dispatched to a single query handler. Implementations may opt for invoking several query handlers and then choosing a response from single one for performance or resilience reasons.

When no handlers are available that can answer the given query, the return Publisher will be completed with a NoHandlerForQueryException.

Type Parameters:

Q - the payload type of the streaming query

R - the response type of the streaming query

Parameters:

query - the streaming query message

Returns:

a Publisher of responses

scatterGather

<Q,R> Stream<QueryResponseMessage<R>> scatterGather(@Nonnull
                                                    QueryMessage<Q,R> query,
                                                    long timeout,
                                                    @Nonnull
                                                    TimeUnit unit)

Dispatch the given query to all QueryHandlers subscribed to the given query's queryName/responseType. Returns a stream of results which blocks until all handlers have processed the request or when the timeout occurs.

If no handlers are available to provide a result, or when all available handlers throw an exception while attempting to do so, the returned Stream is empty.

Note that any terminal operation (such as Stream.forEach(Consumer)) on the Stream may cause it to block until the timeout has expired, awaiting additional data to include in the stream.

Type Parameters:

Q - the payload type of the query

R - the response type of the query

Parameters:

query - the query

timeout - time to wait for results

unit - unit for the timeout

Returns:

stream of query results

subscriptionQuery

default <Q,I,U> SubscriptionQueryResult<QueryResponseMessage<I>,SubscriptionQueryUpdateMessage<U>> subscriptionQuery(@Nonnull
                                                                                                                     SubscriptionQueryMessage<Q,I,U> query)

Dispatch the given query to a single QueryHandler subscribed to the given query's queryName/initialResponseType/updateResponseType. The result is lazily created and there will be no execution of the query handler before there is a subscription to the initial result. In order not to miss updates, the query bus will queue all updates which happen after the subscription query is done and once the subscription to the flux is made, these updates will be emitted.

If there is an error during retrieving or consuming initial result, stream for incremental updates is NOT interrupted.

If there is an error during emitting an update, subscription is cancelled causing further emits not reaching the destination.

The buffer size which accumulates the updates (not to be missed) is Queues.SMALL_BUFFER_SIZE.

Type Parameters:

Q - the payload type of the query

I - the response type of the query

U - the incremental response types of the query

Parameters:

query - the query

Returns:

query result containing initial result and incremental updates

subscriptionQuery

@Deprecated
default <Q,I,U> SubscriptionQueryResult<QueryResponseMessage<I>,SubscriptionQueryUpdateMessage<U>> subscriptionQuery(@Nonnull
                                                                                                                                 SubscriptionQueryMessage<Q,I,U> query,
                                                                                                                                 SubscriptionQueryBackpressure backpressure,
                                                                                                                                 int updateBufferSize)

Deprecated. in favour of using {subscriptionQuery(SubscriptionQueryMessage, int)}

Dispatch the given query to a single QueryHandler subscribed to the given query's queryName/initialResponseType/updateResponseType. The result is lazily created and there will be no execution of the query handler before there is a subscription to the initial result. In order not to miss updates, the query bus will queue all updates which happen after the subscription query is done and once the subscription to the flux is made, these updates will be emitted.

If there is an error during retrieving or consuming initial result, stream for incremental updates is NOT interrupted.

If there is an error during emitting an update, subscription is cancelled causing further emits not reaching the destination.

Provided backpressure mechanism will be used to deal with fast emitters.

Type Parameters:

Q - the payload type of the query

I - the response type of the query

U - the incremental response types of the query

Parameters:

query - the query

backpressure - the backpressure mechanism to be used for emitting updates

updateBufferSize - the size of buffer which accumulates updates before subscription to the flux is made

Returns:

query result containing initial result and incremental updates

subscriptionQuery

default <Q,I,U> SubscriptionQueryResult<QueryResponseMessage<I>,SubscriptionQueryUpdateMessage<U>> subscriptionQuery(@Nonnull
                                                                                                                     SubscriptionQueryMessage<Q,I,U> query,
                                                                                                                     int updateBufferSize)

Dispatch the given query to a single QueryHandler subscribed to the given query's queryName/initialResponseType/updateResponseType. The result is lazily created and there will be no execution of the query handler before there is a subscription to the initial result. In order not to miss updates, the query bus will queue all updates which happen after the subscription query is done and once the subscription to the flux is made, these updates will be emitted.

If there is an error during retrieving or consuming initial result, stream for incremental updates is NOT interrupted.

If there is an error during emitting an update, subscription is cancelled causing further emits not reaching the destination.

Type Parameters:

Q - the payload type of the query

I - the response type of the query

U - the incremental response types of the query

Parameters:

query - the query

updateBufferSize - the size of buffer which accumulates updates before subscription to the flux is made

Returns:

query result containing initial result and incremental updates

queryUpdateEmitter

QueryUpdateEmitter queryUpdateEmitter()

Gets the QueryUpdateEmitter associated with this QueryBus.

Returns:

the associated QueryUpdateEmitter