Package org.axonframework.messaging.eventstreaming

Interface EventCriteria

All Known Subinterfaces:
EventCriterion, EventTypeRestrictableEventCriteria
public sealed interface EventCriteria permits EventCriterion, EventTypeRestrictableEventCriteria (not exhaustive)
Describes the criteria for EventStoreTransaction#source(SourcingCondition) sourcing or
invalid reference 
streaming
events. The criteria are used to filter the events to read from a streamable event source (like an Event Store).

Filtering

Filtering happens based on the tags of the event, indicating an association during publishing of the event. For example, a student enrolling in a course may have the "student" tag with the value of its id. This value is determined during publishing by the TagResolver. If an instance of a criteria contains multiple tags, the event must contain all of them to be considered a match. 
     
     EventCriteria criteria = EventCriteria
         .havingTags(Tag.of("student", "matchingStudent"))

After first defining the tags to filter on through havingTags(Tag...) or one of its variants, the scope of the read on the event store can further be limited on the type, through EventTypeRestrictableEventCriteria.andBeingOneOfTypes(QualifiedName...). This is optional, and will default to all types if not specified. 

     
     EventCriteria criteria = EventCriteria
         // Reads all events with this tag
         .havingTags(Tag.of("student", "matchingStudent"))
         .or()
         // Only reads events with this tag and type
         .havingTags("course", "matchingCourse")
         .andBeingOneOfTypes(new QualifiedName("CourseRegistered"))

When using an event store that supports it, using such a type-filtered criteria will narrow the scope of your transaction, leading to better performance and a lower chance of concurrency conflicts. So while optional, it's recommended to use it when possible.

Combining

You can combine multiple criteria using either(EventCriteria...), or in a fluent fashion using or(). This allows you to create more complex criteria that match events based on multiple tags or types. However, it's not possible to create AND conditions between multiple criteria. 
     
     EventCriteria criteria = EventCriteria
         .havingTags(Tag.of("student", "matchingStudent"))
         .andBeingOneOfTypes(new QualifiedName("StudentEnrolled"))
         .or()
         .havingTags("course", "matchingCourse")
         .andBeingOneOfTypes(new QualifiedName("CourseRegistered"))

Examples

To make it easier to understand how the criteria work, here are some examples. These examples all have the following events in the event store:
  • Event [StudentRegistered, student -> matchingStudent]
  • Event [CourseRegistered, course -> matchingCourse]
  • Event [StudentAssignedToCourse, student -> nonMatchingStudent, course -> matchingCourse]
  • Event [StudentAssignedToCourse, student -> matchingStudent, course -> nonMatchingCourse]
  • Event [StudentAssignedToCourse, student -> matchingStudent, course -> matchingStudent]
  • Event [StudentRegistered, student -> nonMatchingStudent]
  • Event [CourseRegistered, course -> nonMatchingCourse]
  • Event [StudentAssignedToCourse, student -> nonMatchingStudent, course -> nonMatchingCourse]

Example 1

     
     EventCriteria criteria = EventCriteria
         .havingTags(Tag.of("student", "matchingStudent"))
This criteria will match all events with the tag "student" and the value "matchingStudent". The following events will match:
  • Event [StudentRegistered, student -> matchingStudent]
  • Event [StudentAssignedToCourse, student -> matchingStudent, course -> nonMatchingCourse]
  • Event [StudentAssignedToCourse, student -> matchingStudent, course -> matchingStudent]

Example 2

We don't have to pass in tags as Tag instances. We can also pass them in as key-value pairs: 
     
     EventCriteria criteria = EventCriteria
         .havingTags("student", "matchingStudent", "course", "matchingCourse")

This criteria will match all events with both the "student" tag of value "matchingStudent" and the "course" tag with value "matchingStudent". The following events will match:

  • Event [StudentRegistered, student -> matchingStudent]
  • Event [StudentAssignedToCourse, student -> matchingStudent, course -> matchingStudent]

Example 3

We can also combine multiple criteria using or(EventCriteria), such as searching for multiple students: 
     
     EventCriteria criteria = EventCriteria
         .havingTags("student", "matchingStudent")
         .or()
         .havingTags("student", "nonMatchingStudent")

This works as an OR condition, meaning that the following events will match:

  • Event [StudentRegistered, student -> matchingStudent]
  • Event [StudentAssignedToCourse, student -> matchingStudent, course -> nonMatchingCourse]
  • Event [StudentAssignedToCourse, student -> nonMatchingStudent, course -> matchingCourse]
  • Event [StudentAssignedToCourse, student -> nonMatchingStudent, course -> nonMatchingCourse]

Example 4

Last but not least, let's say that we only want the "StudentRegistered" events for the "matchingStudent". This can be done by using the EventTypeRestrictableEventCriteria.andBeingOneOfTypes(QualifiedName...) method: 
     
     EventCriteria criteria = EventCriteria
         .havingTags("student", "matchingStudent")
         .andBeingOneOfTypes(new QualifiedName("StudentRegistered"))
The following events will match:
  • Event [StudentRegistered, student -> matchingStudent]
See EventTypeRestrictableEventCriteria for all the methods available to you.

Flattening

The criteria can be flattened into a Set of EventCriterion instances, which are a specialized representation of the criteria that are guaranteed to be non-nested. As such, these instances can be used to read their EventCriterion.tags() and EventCriterion.types() without the need to interpret conditions, as this is already done by the flatten method.
Since:
5.0.0
Author:
Michal Negacz, Milan Savić, Marco Amann, Sara Pellegrini, Steven van Beelen, Mitchell Herrijgers

  • Method Details

    • havingAnyTag

      static EventTypeRestrictableEventCriteria havingAnyTag()
      Construct a EventCriteria that allows any events.

      Use this instance when all events are of interest during

      invalid reference 
      streaming
      or when there are no consistency boundaries to validate during
      invalid reference 
      appending
      . Note that this EventCriteria does not make sense for
      invalid reference 
      sourcing
      , as it is not recommended to source the entire event store.

      Event though this criteria will not filter any tags, you can limit the types of events to be matched by using the EventTypeRestrictableEventCriteria.andBeingOneOfTypes(Set) method.

      Returns:
      An EventCriteria that contains no criteria at all.

    • havingTags

      static EventTypeRestrictableEventCriteria havingTags(@Nonnull Set<Tag> tags)
      Define that the event must contain all the provided tags to match. These tags function in an AND relation, meaning that an event must have all tags to match. A partial match is not sufficient.

      You can further limit the types of events to be matched by using the EventTypeRestrictableEventCriteria.andBeingOneOfTypes(Set) method.

      Parameters:
      tags - The tags to match against.
      Returns:
      The completed EventCriteria instance.

    • havingTags

      static EventTypeRestrictableEventCriteria havingTags(@Nonnull Tag... tags)
      Define that the event must contain all the provided tags to match. These tags function in an AND relation, meaning that an event must have all tags to match. A partial match is not sufficient.

      You can further limit the types of events to be matched by using the EventTypeRestrictableEventCriteria.andBeingOneOfTypes(Set) method.

      Parameters:
      tags - The tags to match against.
      Returns:
      The completed EventCriteria instance.

    • havingTags

      static EventTypeRestrictableEventCriteria havingTags(@Nonnull String... tags)
      Define, as key-value pairs, that the event must contain all the provided tags to match. These tags function in an AND relation, meaning that an event must have all tags to match. A partial match is not sufficient.

      You can further limit the types of events to be matched by using the EventTypeRestrictableEventCriteria.andBeingOneOfTypes(Set) method.

      Parameters:
      tags - The tags to match against.
      Returns:
      The completed EventCriteria instance.

    • or

      EventCriteria or(EventCriteria criteria)
      Create an EventCriteria that matches events from either this or the given criteria EventCriteria.
      Parameters:
      criteria - The EventCriteria to match in addition to this EventCriteria.
      Returns:
      An EventCriteria that matches events that match either this EventCriteria or the given EventCriteria.

    • either

      static EventCriteria either(@Nonnull Collection<EventCriteria> eventCriteria)
      Create an EventCriteria that matches events that match either of the given EventCriteria.
      Parameters:
      eventCriteria - The EventCriteria of which one must match.
      Returns:
      An EventCriteria that matches events that match either of the given EventCriteria.

    • either

      static EventCriteria either(EventCriteria... eventCriteria)
      Create an EventCriteria that matches events that match either of the given EventCriteria.
      Parameters:
      eventCriteria - The EventCriteria of which one must match.
      Returns:
      An EventCriteria that matches events that match either of the given EventCriteria.

    • or

      default OrEventCriteriaBuilder or()
      Start a builder to construct an additional EventCriteria that will be combined with this one using or(EventCriteria). The resulting EventCriteria will match events that match either this EventCriteria or the built one.
      Returns:
      A builder to construct an EventCriteria instance that will match events that match either this EventCriteria or the built one.

    • matches

      boolean matches(@Nonnull QualifiedName type, @Nonnull Set<Tag> tags)
      Indicates whether the given type and tags matches the types and tags defined in this or these criteria. If no types are defined, any given type will be considered a match.
      Parameters:
      type - The type to match against this criteria instance.
      tags - The tags to match against this criteria instance.
      Returns:
      true if the type matches, otherwise false.

    • flatten

      Set<EventCriterion> flatten()
      Flatten this, possibly nested, EventCriteria into a Set of EventCriterion. These EventCriterion instances can be used by the
      invalid reference 
      EventStore
      to construct queries without the need to interpret the criteria.
      Returns:
      The flattened set of EventCriteria.

    • hasCriteria

      boolean hasCriteria()
      Indicates whether this EventCriteria instance has any criteria defined.
      Returns:
      true if this EventCriteria instance has criteria defined, otherwise false.