Package org.axonframework.messaging.eventhandling

Class SimpleEventBus

java.lang.Object
org.axonframework.messaging.eventhandling.SimpleEventBus
All Implemented Interfaces:
DescribableComponent, SubscribableEventSource, EventBus, EventSink
public class SimpleEventBus extends Object implements EventBus
Simple implementation of the EventBus that provides synchronous event publication with optional ProcessingContext integration for transactional event handling.

This event bus supports two publication modes depending on whether a ProcessingContext is provided:

  • Immediate publication (context is null): Events are published directly to all subscribers without any queueing or lifecycle management. This mode is useful for fire-and-forget event publication outside of any transactional boundary.
  • Deferred publication (context is provided): Events are queued and published during the PREPARE_COMMIT phase of the processing lifecycle. This ensures that events are only published if the processing context successfully reaches the commit phase, providing transactional consistency.

ProcessingContext Integration:

When events are published with a ProcessingContext, this event bus registers lifecycle hooks on the first publication within that context:

  • A onPrepareCommit handler that publishes all queued events to subscribers
  • A doFinally handler that cleans up the event queue to free memory
All events published within the same ProcessingContext are queued together and published as a single batch during the PREPARE_COMMIT phase. If additional events are published by event handlers during this phase, they are also processed in the same phase to ensure complete event propagation.

Publication Restrictions:

Event publication is forbidden once the ProcessingContext has been committed. Attempting to publish events during or after the COMMIT phase will result in an IllegalStateException. This restriction ensures that events cannot be published after the transactional boundary has been crossed, preventing inconsistent state.

Example usage: 


 // Immediate publication (no transactional context)
 EventBus eventBus = new SimpleEventBus();
 eventBus.publish(null, List.of(new GenericEventMessage<>(new OrderPlacedEvent())));

 // Deferred publication within a UnitOfWork
 UnitOfWork uow = unitOfWorkFactory.create();
 uow.runOnInvocation(ctx -> {
     eventBus.publish(ctx, List.of(new GenericEventMessage<>(new OrderPlacedEvent())));
     // Events are not yet published - they're queued
 });
 uow.execute(); // Events are published during PREPARE_COMMIT phase
Since:
0.5
Author:
Allard Buijze, Mateusz Nowak, René de Waele

  • Constructor Details

    • SimpleEventBus

      public SimpleEventBus()
      Instantiate an SimpleEventBus.

  • Method Details

    • subscribe

      public Registration subscribe(@Nonnull BiFunction<List<? extends EventMessage>,ProcessingContext,CompletableFuture<?>> eventsBatchConsumer)
      Description copied from interface: SubscribableEventSource
      Subscribe the given eventsBatchConsumer to this event source. When subscribed, it will receive all events published to this source since the subscription.

      If the given eventsBatchConsumer is already subscribed, nothing happens.

      Note on ProcessingContext: The ProcessingContext parameter passed to the consumer may be null. When null, it is the responsibility of the registered eventsBatchConsumer to create an appropriate ProcessingContext as needed for processing the events.

      Specified by:
      subscribe in interface SubscribableEventSource
      Parameters:
      eventsBatchConsumer - The event batches consumer to subscribe.
      Returns:
      A Registration handle to unsubscribe the eventsBatchConsumer. When unsubscribed, it will no longer receive events.

    • publish

      public CompletableFuture<Void> publish(@Nullable ProcessingContext context, @Nonnull List<EventMessage> events)
      Description copied from interface: EventSink
      Publishes the given events within the given context, when present.

      When present, the post invocation phase is used to publish the events. As a consequence, the resulting CompletableFuture completes when the events are staged in that phase.

      When no ProcessingContext is provided, implementers of this interface may choose to create a ProcessingContext when necessary.

      Specified by:
      publish in interface EventSink
      Parameters:
      context - The processing context, if any, to publish the given events in.
      events - The events to publish in this sink.
      Returns:
      A CompletableFuture of Void. When this completes and a non-null context was given, this means the events have been successfully staged. When a null context was provided, successful completion of this future means the events where published.

    • describeTo

      public void describeTo(@Nonnull ComponentDescriptor descriptor)
      Description copied from interface: DescribableComponent
      Describe the properties of this DescribableComponent with the given descriptor.

      Components should call the appropriate describeProperty methods on the descriptor to register their properties. The descriptor is responsible for determining how these properties are formatted and structured in the final output.

      Best Practices: As a general rule, all relevant fields of a DescribableComponent implementation should be described in this method. However, developers have discretion to include only the fields that make sense in the context. Not every field may be meaningful for description purposes, especially internal implementation details. Furthermore, components might want to expose different information based on their current state. The final decision on what properties to include lies with the person implementing the describeTo method, who should focus on providing information that is useful for understanding the component's configuration and state.

      Example implementation: 

       public void describeTo(ComponentDescriptor descriptor) {
     descriptor.describeProperty("name", this.name);
     descriptor.describeProperty("enabled", this.enabled);
     descriptor.describeProperty("configuration", this.configuration); // A nested component
     descriptor.describeProperty("handlers", this.eventHandlers);      // A collection
 }
      Specified by:
      describeTo in interface DescribableComponent
      Parameters:
      descriptor - The component descriptor to describe this DescribableComponentn its properties in.