org.axonframework.eventsourcing.eventstore

Interface EventStorageEngine

All Known Implementing Classes:

AbstractEventStorageEngine, BatchingEventStorageEngine, FilteringEventStorageEngine, InMemoryEventStorageEngine, JdbcEventStorageEngine, JpaEventStorageEngine, JpaEventStorageEngine, SequenceEventStorageEngine

public interface EventStorageEngine

Provides a mechanism to append as well as retrieve events from an underlying storage like a database. An event storage engine can also be used to store and fetch aggregate snapshot events.

Author:

Rene de Waele

Method Summary

Modifier and Type	Method and Description
default void	appendEvents(EventMessage<?>... events) Append one or more events to the event storage.
void	appendEvents(List<? extends EventMessage<?>> events) Append a list of events to the event storage.
default TrackingToken	createHeadToken() Creates a token that is at the head of an event stream - that tracks all new events.
default TrackingToken	createTailToken() Creates a token that is at the tail of an event stream - that tracks events from the beginning of time.
default TrackingToken	createTokenAt(Instant dateTime) Creates a token that tracks all events after given dateTime.
default Optional<Long>	lastSequenceNumberFor(String aggregateIdentifier) Returns the last known sequence number for the given aggregateIdentifier.
default DomainEventStream	readEvents(String aggregateIdentifier) Get a DomainEventStream containing all events published by the aggregate with given aggregateIdentifier.
DomainEventStream	readEvents(String aggregateIdentifier, long firstSequenceNumber) Get a DomainEventStream containing all events published by the aggregate with given aggregateIdentifier starting with the first event having a sequence number that is equal or larger than the given firstSequenceNumber.
Stream<? extends TrackedEventMessage<?>>	readEvents(TrackingToken trackingToken, boolean mayBlock) Open an event stream containing all events stored since given tracking token.
Optional<DomainEventMessage<?>>	readSnapshot(String aggregateIdentifier) Try to load a snapshot event of the aggregate with given aggregateIdentifier.
void	storeSnapshot(DomainEventMessage<?> snapshot) Store an event that contains a snapshot of an aggregate.

Method Detail

appendEvents

default void appendEvents(@Nonnull
                          EventMessage<?>... events)

Append one or more events to the event storage. Events will be appended in the order that they are offered in.

Note that all events should have a unique event identifier. When storing domain events events should also have a unique combination of aggregate id and sequence number.

By default this method creates a list of the offered events and then invokes appendEvents(List).

Parameters:

events - Events to append to the event storage

appendEvents

void appendEvents(@Nonnull
                  List<? extends EventMessage<?>> events)

Append a list of events to the event storage. Events will be appended in the order that they are offered in.

Note that all events should have a unique event identifier. When storing domain events events should also have a unique combination of aggregate id and sequence number.

Parameters:

events - Events to append to the event storage

storeSnapshot

void storeSnapshot(@Nonnull
                   DomainEventMessage<?> snapshot)

Store an event that contains a snapshot of an aggregate. If the event storage already contains a snapshot for the same aggregate, then it will be replaced with the given snapshot.

Parameters:

snapshot - The snapshot event of the aggregate that is to be stored

readEvents

Stream<? extends TrackedEventMessage<?>> readEvents(@Nullable
                                                    TrackingToken trackingToken,
                                                    boolean mayBlock)

Open an event stream containing all events stored since given tracking token. The returned stream is comprised of events from aggregates as well as other application events. Pass a trackingToken of null to open a stream containing all available events.

If the value of the given mayBlock is true the returned stream is allowed to block while waiting for new event messages if the end of the stream is reached.

Parameters:

trackingToken - Object describing the global index of the last processed event or null to create a stream of all events in the store

mayBlock - If true the storage engine may optionally choose to block to wait for new event messages if the end of the stream is reached.

Returns:

A stream containing all tracked event messages stored since the given tracking token

readEvents

default DomainEventStream readEvents(@Nonnull
                                     String aggregateIdentifier)

Get a DomainEventStream containing all events published by the aggregate with given aggregateIdentifier. By default calling this method is shorthand for an invocation of readEvents(String, long) with a sequence number of 0.

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.

Parameters:

aggregateIdentifier - The identifier of the aggregate to return an event stream for

Returns:

A non-blocking DomainEventStream of the given aggregate

readEvents

DomainEventStream readEvents(@Nonnull
                             String aggregateIdentifier,
                             long firstSequenceNumber)

Get a DomainEventStream containing all events published by the aggregate with given aggregateIdentifier starting with the first event having a sequence number that is equal or larger than the given firstSequenceNumber.

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.

Parameters:

aggregateIdentifier - The identifier of the aggregate

firstSequenceNumber - The expected sequence number of the first event in the returned stream

Returns:

A non-blocking DomainEventStream of the given aggregate

readSnapshot

Optional<DomainEventMessage<?>> readSnapshot(@Nonnull
                                             String aggregateIdentifier)

Try to load a snapshot event of the aggregate with given aggregateIdentifier. If the storage engine has no snapshot event of the aggregate, an empty Optional is returned.

Parameters:

aggregateIdentifier - The identifier of the aggregate

Returns:

An optional with a snapshot of the aggregate

lastSequenceNumberFor

default Optional<Long> lastSequenceNumberFor(@Nonnull
                                             String aggregateIdentifier)

Returns the last known sequence number for the given aggregateIdentifier.

While it's recommended to use the sequence numbers from the DomainEventStream, there are cases where knowing the sequence number is required, without having read the actual events. In such case, this method is a viable alternative.

Parameters:

aggregateIdentifier - The identifier to find the last sequence number for

Returns:

an optional with the highest sequence number, or an empty optional if the aggregate identifier wasn't found

createTailToken

default TrackingToken createTailToken()

Creates a token that is at the tail of an event stream - that tracks events from the beginning of time.

Returns:

a tracking token at the tail of an event stream, if event stream is empty null is returned

createHeadToken

default TrackingToken createHeadToken()

Creates a token that is at the head of an event stream - that tracks all new events.

Returns:

a tracking token at the head of an event stream, if event stream is empty null is returned

createTokenAt

default TrackingToken createTokenAt(@Nonnull
                                    Instant dateTime)

Creates a token that tracks all events after given dateTime. If there is an event exactly at the given dateTime, it will be tracked too.

Parameters:

dateTime - The date and time for determining criteria how the tracking token should be created. A tracking token should point to very first event before this date and time.

Returns:

a tracking token at the given dateTime, if there aren't events matching this criteria null is returned