Package org.axonframework.eventsourcing.eventstore.jpa

Class AggregateBasedJpaEventStorageEngine

java.lang.Object

org.axonframework.eventsourcing.eventstore.jpa.AggregateBasedJpaEventStorageEngine

All Implemented Interfaces:

DescribableComponent, EventStorageEngine

public class AggregateBasedJpaEventStorageEngine
extends Object
implements EventStorageEngine

An EventStorageEngine implementation that uses JPA to store and fetch events from an aggregate-based event storage solution.

By default, the payload of events is stored as a converted blob of bytes. Other columns are used to store meta-data that allow quick finding of events for a specific aggregates in the correct order.

Since:

5.0.0

Author:

Mateusz Nowak, Steven van Beelen

Nested Class Summary

Nested classes/interfaces inherited from interface org.axonframework.eventsourcing.eventstore.EventStorageEngine

EventStorageEngine.AppendTransaction<R>

Constructor Summary

Constructors

Constructor	Description
AggregateBasedJpaEventStorageEngine(TransactionalExecutorProvider<jakarta.persistence.EntityManager> transactionalExecutorProvider, EventConverter converter, UnaryOperator<AggregateBasedJpaEventStorageEngineConfiguration> configurer)	Constructs an AggregateBasedJpaEventStorageEngine with the given parameters.

Method Summary

Modifier and Type	Method	Description
CompletableFuture<EventStorageEngine.AppendTransaction<?>>	appendEvents(AppendCondition condition, ProcessingContext processingContext, List<TaggedEventMessage<?>> events)	Appends a List of events to the underlying storage solution.
void	close()	Releases any resources associated with this engine.
void	describeTo(ComponentDescriptor descriptor)	Describe the properties of this DescribableComponent with the given descriptor.
CompletableFuture<TrackingToken>	firstToken()	Creates a TrackingToken that is at the first position of an event stream.
CompletableFuture<TrackingToken>	latestToken()	Creates a TrackingToken that is at the latest position of an event stream.
MessageStream<EventMessage>	source(SourcingCondition condition)	Creates a finite MessageStream of events matching the given condition.
MessageStream<EventMessage>	stream(StreamingCondition condition)	Creates an infinite MessageStream of events matching the given condition.
CompletableFuture<TrackingToken>	tokenAt(Instant at)	Creates a TrackingToken that tracks all events after the given at.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.axonframework.eventsourcing.eventstore.EventStorageEngine

appendEvents

Constructor Details

AggregateBasedJpaEventStorageEngine

public AggregateBasedJpaEventStorageEngine(@Nonnull
 TransactionalExecutorProvider<jakarta.persistence.EntityManager> transactionalExecutorProvider,
 @Nonnull
 EventConverter converter,
 @Nonnull
 UnaryOperator<AggregateBasedJpaEventStorageEngineConfiguration> configurer)

Constructs an AggregateBasedJpaEventStorageEngine with the given parameters.

Parameters:

transactionalExecutorProvider - The transactional executor provider for this storage solution.

converter - The converter used to convert the Message.payload() and Message.metadata() to a byte[].

configurer - A unary operator of the AggregateBasedJpaEventStorageEngineConfiguration that customizes the AggregateBasedJpaEventStorageEngine under construction.

Method Details

appendEvents

public CompletableFuture<EventStorageEngine.AppendTransaction<?>> appendEvents(@Nonnull
 AppendCondition condition,
 @Nullable
 ProcessingContext processingContext,
 @Nonnull
 List<TaggedEventMessage<?>> events)

Description copied from interface: EventStorageEngine

Appends a List of events to the underlying storage solution.

Events will be appended in the order that they are offered in, validating the given condition before being stored. Note that all events should have a unique event identifier. Tags paired with the events will be stored as well.

Implementations may be able to detect conflicts during the append stage. In such case, the returned completable future will complete exceptionally, indicating such conflict. Other implementations may delay such checks until the EventStorageEngine.AppendTransaction.commit() is called.

Called during the PREPARE_COMMIT phase.

Specified by:

appendEvents in interface EventStorageEngine

Parameters:

condition - The condition describing the transactional requirements for the append transaction

processingContext - The current ProcessingContext, if any.

events - The List of events to append to the underlying storage solution.

Returns:

A transaction instance that can be committed or rolled back.

source

public MessageStream<EventMessage> source(@Nonnull
 SourcingCondition condition)

Description copied from interface: EventStorageEngine

Creates a finite MessageStream of events matching the given condition.

The final entry of the stream always contains a ConsistencyMarker in the MessageStream.Entry's resources, paired with a TerminalEventMessage. This ConsistencyMarker should be used to construct the AppendCondition when

invalid reference

appending events

.

The condition dictates the sequence to load based on the EventsCondition.criteria(). Additionally, an optional SourcingCondition.start() and

invalid reference

SourcingCondition#end()

position may be provided.

The returned stream is finite, i.e. it should not block to wait for further events if the end of the event stream of the aggregate is reached.

Specified by:

source in interface EventStorageEngine

Parameters:

condition - The SourcingCondition dictating the stream of events to source.

Returns:

A finite MessageStream of events matching the given condition.

stream

public MessageStream<EventMessage> stream(@Nonnull
 StreamingCondition condition)

Description copied from interface: EventStorageEngine

Creates an infinite MessageStream of events matching the given condition.

The condition may dictate the StreamingCondition.position() to start streaming from, as well as define filter criteria for the returned MessageStream.

Specified by:

stream in interface EventStorageEngine

Parameters:

condition - The StreamingCondition dictating the StreamingCondition.position() to start streaming from, as well as the filter criteria used for the returned MessageStream.

Returns:

An infinite MessageStream of events matching the given condition.

firstToken

public CompletableFuture<TrackingToken> firstToken()

Description copied from interface: EventStorageEngine

Creates a TrackingToken that is at the first position of an event stream.

In other words, a token that tracks events from the beginning of time.

Specified by:

firstToken in interface EventStorageEngine

Returns:

A CompletableFuture of a TrackingToken at the first position of an event stream.

latestToken

public CompletableFuture<TrackingToken> latestToken()

Description copied from interface: EventStorageEngine

Creates a TrackingToken that is at the latest position of an event stream.

In other words, a token that tracks all new events from this point forward.

Specified by:

latestToken in interface EventStorageEngine

Returns:

A CompletableFuture of a TrackingToken at the latest position of an event stream.

tokenAt

public CompletableFuture<TrackingToken> tokenAt(@Nonnull
 Instant at)

Description copied from interface: EventStorageEngine

Creates a TrackingToken that tracks all events after the given at.

If there is an event exactly at the given at, it will be tracked too.

Specified by:

tokenAt in interface EventStorageEngine

Parameters:

at - The Instant determining how the TrackingToken should be created. A tracking token should point to very first event before this Instant.

Returns:

A CompletableFuture of a TrackingToken at the given at, if there aren't events matching this criteria null is returned

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.

close

public void close()

Releases any resources associated with this engine.