Package org.axonframework.messaging.queryhandling

Interface QueryUpdateEmitter

All Superinterfaces:
DescribableComponent
All Known Implementing Classes:
SimpleQueryUpdateEmitter
public interface QueryUpdateEmitter extends DescribableComponent
Query-specific component that interacts with subscription queries about update, errors, and when there are no more update.

Implementations of the QueryUpdateEmitter are expected to be context-aware, to ensure operations occur within the correct order of (for example) the lifecycle of an event handling function.

Since:
3.3.0
Author:
Milan Savic, Steven van Beelen

  • Method Details

    • forContext

      static QueryUpdateEmitter forContext(ProcessingContext context)
      Creates a query update emitter for the given ProcessingContext.

      Use this from within a message handler, or any other method that receives a ProcessingContext, instead of emitting directly through a QueryBus: the emitter returned here is bound to that context, ensuring updates are emitted in the correct order relative to the lifecycle of whatever is currently being handled.

      Every invocation returns a fresh instance bound to the given context, since context may override resources on top of a shared parent (see ProcessingContext.withResource(org.axonframework.messaging.core.Context.ResourceKey<T>, T)) - reusing an instance across such branches would risk it silently operating against the wrong one.

      Parameters:
      context - the ProcessingContext to create the emitter for
      Returns:
      a fresh emitter specific for the given context

    • emit

      default <Q> void emit(Class<Q> queryType, Predicate<? super Q> filter, @Nullable Object update)
      Emits given update to subscription queries matching the given queryType and given filter.
      Type Parameters:
      Q - the type of the QueryMessage to filter on
      Parameters:
      queryType - the type of the QueryMessage to filter on
      filter - a predicate to filter matching subscription queries based on the Message.payload() converted to the given queryType
      update - the incremental update to emit for subscription queries matching the given filter
      Throws:
      MessageTypeNotResolvedException - if the given queryType has no known MessageType equivalent required to filter the Message.payload()
      ConversionException - if the Message.payload() could not be converted to the given queryType to perform the given filter. Will only occur if a MessageType could be found for the given queryType

    • emit

      <Q> void emit(Class<Q> queryType, Predicate<? super Q> filter, Supplier<Object> updateSupplier)
      Emits the outcome of the updateSupplier to subscription queries matching the given queryType and given filter.

      The updateSupplier is only invoked whenever there are matching queries.

      Type Parameters:
      Q - the type of the QueryMessage to filter on
      Parameters:
      queryType - the type of the QueryMessage to filter on
      filter - a predicate to filter matching subscription queries based on the Message.payload() converted to the given queryType
      updateSupplier - the update supplier to emit for subscription queries matching the given queryType and filter
      Throws:
      MessageTypeNotResolvedException - if the given queryType has no known MessageType equivalent required to filter the Message.payload()
      ConversionException - if the Message.payload() could not be converted to the given queryType to perform the given filter. Will only occur if a MessageType could be found for the given queryType

    • emitAndCount

      default <Q> OptionalInt emitAndCount(Class<Q> queryType, Predicate<? super Q> filter, Supplier<Object> updateSupplier)
      Emits the outcome of the updateSupplier to subscription queries matching the given queryType and given filter, returning the number of subscription queries the update was emitted to.

      Implementations that cannot determine this number return OptionalInt.empty() instead.

      A subscription query to which delivery of the update fails (for example due to a full update buffer) is excluded from this count, even though that failure still terminates the subscription.

      Type Parameters:
      Q - the type of the QueryMessage to filter on
      Parameters:
      queryType - the type of the QueryMessage to filter on
      filter - a predicate to filter matching subscription queries based on the Message.payload() converted to the given queryType
      updateSupplier - the update supplier to emit for subscription queries matching the given queryType and filter
      Returns:
      the number of subscription queries the update was emitted to as an OptionalInt, which is empty when we couldn't match
      Throws:
      MessageTypeNotResolvedException - if the given queryType has no known MessageType equivalent required to filter the Message.payload()
      ConversionException - if the Message.payload() could not be converted to the given queryType to perform the given filter. Will only occur if a MessageType could be found for the given queryType

    • emit

      default void emit(QualifiedName queryName, Predicate<Object> filter, @Nullable Object update)
      Emits given update to subscription queries matching the given queryName and given filter.
      Parameters:
      queryName - the qualified name of the Message.type() to filter on
      filter - a predicate to filter matching subscription queries based on the raw Message.payload()
      update - the incremental update to emit for subscription queries matching the given filter

    • emit

      void emit(QualifiedName queryName, Predicate<Object> filter, Supplier<Object> updateSupplier)
      Emits the outcome of the updateSupplier to subscription queries matching the given queryName and given filter.

      The updateSupplier is only invoked whenever there are matching queries.

      Parameters:
      queryName - the qualified name of the Message.type() to filter on
      filter - a predicate to filter matching subscription queries based on the raw Message.payload()
      updateSupplier - the update supplier to emit for subscription queries matching the given queryName and filter

    • emitAndCount

      default OptionalInt emitAndCount(QualifiedName queryName, Predicate<Object> filter, Supplier<Object> updateSupplier)
      Emits the outcome of the updateSupplier to subscription queries matching the given queryName and given filter, returning the number of subscription queries the update was emitted to.

      Implementations that cannot determine this number return OptionalInt.empty() instead.

      A subscription query to which delivery of the update fails (for example due to a full update buffer) is excluded from this count, even though that failure still terminates the subscription.

      Parameters:
      queryName - the qualified name of the Message.type() to filter on
      filter - a predicate to filter matching subscription queries based on the raw Message.payload()
      updateSupplier - the update supplier to emit for subscription queries matching the given queryName and filter
      Returns:
      the number of subscription queries the update was emitted to as an OptionalInt, which is empty when we couldn't match

    • complete

      <Q> void complete(Class<Q> queryType, Predicate<? super Q> filter)
      Completes subscription queries matching the given queryType and filter.
      Type Parameters:
      Q - the type of the QueryMessage to filter on
      Parameters:
      queryType - the type of the QueryMessage to filter on
      filter - a predicate to filter matching subscription queries based on the Message.payload() converted to the given queryType
      Throws:
      MessageTypeNotResolvedException - if the given queryType has no known MessageType equivalent required to filter the Message.payload()
      ConversionException - if the Message.payload() could not be converted to the given queryType to perform the given filter. Will only occur if a MessageType could be found for the given queryType

    • completeAndCount

      default <Q> OptionalInt completeAndCount(Class<Q> queryType, Predicate<? super Q> filter)
      Completes subscription queries matching the given queryType and filter, returning the number of subscription queries that were completed.

      Implementations that cannot determine this number return OptionalInt.empty() instead.

      A subscription query for which completion fails is excluded from this count.

      Type Parameters:
      Q - the type of the QueryMessage to filter on.
      Parameters:
      queryType - the type of the QueryMessage to filter on.
      filter - a predicate to filter matching subscription queries based on the Message.payload() converted to the given queryType
      Returns:
      the number of subscription queries that were completed as an OptionalInt, which is empty when we couldn't match
      Throws:
      MessageTypeNotResolvedException - if the given queryType has no known MessageType equivalent required to filter the Message.payload()
      ConversionException - if the Message.payload() could not be converted to the given queryType to perform the given filter. Will only occur if a MessageType could be found for the given queryType

    • complete

      void complete(QualifiedName queryName, Predicate<Object> filter)
      Completes subscription queries matching the given queryName and filter.
      Parameters:
      queryName - the qualified name of the Message.type() to filter on
      filter - a predicate testing the raw Message.payload() as is

    • completeAndCount

      default OptionalInt completeAndCount(QualifiedName queryName, Predicate<Object> filter)
      Completes subscription queries matching the given queryName and filter, returning the number of subscription queries that were completed.

      Implementations that cannot determine this number return OptionalInt.empty() instead.

      A subscription query for which completion fails is excluded from this count.

      Parameters:
      queryName - the qualified name of the Message.type() to filter on
      filter - a predicate testing the raw Message.payload() as is
      Returns:
      the number of subscription queries that were completed as an OptionalInt, which is empty when we couldn't match

    • completeExceptionally

      <Q> void completeExceptionally(Class<Q> queryType, Predicate<? super Q> filter, Throwable cause)
      Completes subscription queries with the given cause matching given queryType and filter.
      Type Parameters:
      Q - the type of the QueryMessage to filter on
      Parameters:
      queryType - the type of the QueryMessage to filter on
      filter - a predicate to filter matching subscription queries based on the Message.payload() converted to the given queryType
      cause - the cause of an error leading to exceptionally complete subscription queries
      Throws:
      MessageTypeNotResolvedException - if the given queryType has no known MessageType equivalent required to filter the Message.payload()
      ConversionException - if the Message.payload() could not be converted to the given queryType to perform the given filter. Will only occur if a MessageType could be found for the given queryType

    • completeExceptionallyAndCount

      default <Q> OptionalInt completeExceptionallyAndCount(Class<Q> queryType, Predicate<? super Q> filter, Throwable cause)
      Completes subscription queries with the given cause matching given queryType and filter, returning the number of subscription queries that were completed exceptionally.

      Implementations that cannot determine this number return OptionalInt.empty() instead.

      A subscription query for which the exceptional completion fails to be delivered is excluded from this count.

      Type Parameters:
      Q - the type of the QueryMessage to filter on
      Parameters:
      queryType - the type of the QueryMessage to filter on
      filter - a predicate to filter matching subscription queries based on the Message.payload() converted to the given queryType
      cause - the cause of an error leading to exceptionally complete subscription queries
      Returns:
      the number of subscription queries that were completed exceptionally as an OptionalInt, which is empty when we couldn't match
      Throws:
      MessageTypeNotResolvedException - if the given queryType has no known MessageType equivalent required to filter the Message.payload()
      ConversionException - if the Message.payload() could not be converted to the given queryType to perform the given filter. Will only occur if a MessageType could be found for the given queryType

    • completeExceptionally

      void completeExceptionally(QualifiedName queryName, Predicate<Object> filter, Throwable cause)
      Completes subscription queries with the given cause matching given queryName and filter.
      Parameters:
      queryName - the qualified name of the Message.type() to filter on
      filter - a predicate to filter matching subscription queries based on the raw Message.payload()
      cause - the cause of an error leading to exceptionally complete subscription queries

    • completeExceptionallyAndCount

      default OptionalInt completeExceptionallyAndCount(QualifiedName queryName, Predicate<Object> filter, Throwable cause)
      Completes subscription queries with the given cause matching given queryName and filter, returning the number of subscription queries that were completed exceptionally.

      Implementations that cannot determine this number return OptionalInt.empty() instead.

      A subscription query for which the exceptional completion fails to be delivered is excluded from this count.

      Parameters:
      queryName - the qualified name of the Message.type() to filter on
      filter - a predicate to filter matching subscription queries based on the raw Message.payload()
      cause - the cause of an error leading to exceptionally complete subscription queries
      Returns:
      the number of subscription queries that were completed exceptionally as an OptionalInt, which is empty when we couldn't match