io.axoniq.axonserver.connector.event

Interface EventChannel

All Known Implementing Classes:

EventChannelImpl

public interface EventChannel

Communication channel for Event related interactions with AxonServer.

Method Summary

Modifier and Type	Method and Description
default CompletableFuture<Confirmation>	appendEvents(Event... events) Append the given events to the Event Store.
CompletableFuture<Confirmation>	appendSnapshot(Event snapshotEvent) Store the given snapshotEvent.
CompletableFuture<InstructionAck>	cancelSchedule(String scheduleToken) Cancels the scheduled publication of an event for which the given scheduleToken was returned.
CompletableFuture<Long>	findHighestSequence(String aggregateId) Find the highest sequence number (i.e.
CompletableFuture<Long>	getFirstToken() Retrieves the Token referring to the first Event in the Event Store.
CompletableFuture<Long>	getLastToken() Retrieves the Token referring to the most recent Event in the Event Store.
CompletableFuture<Long>	getTokenAt(long instant) Retrieves the token referencing the first Event in the Event Store closest to the given instant.
default AggregateEventStream	loadSnapshot(String aggregateIdentifier) Loads the Snapshot Event for the given aggregateIdentifier with the highest sequence number.
default AggregateEventStream	loadSnapshots(String aggregateIdentifier, long maxSequence, int maxResults) Loads Snapshot Events for the given aggregateIdentifier with sequence number lower or equal to maxSequence, returning at most maxResults number of snapshots.
AggregateEventStream	loadSnapshots(String aggregateIdentifier, long initialSequence, long maxSequence, int maxResults) Loads Snapshot Events for the given aggregateIdentifier with sequence number between initialSequence and maxSequence (inclusive), returning at most maxResults number of snapshots.
default AggregateEventStream	openAggregateStream(String aggregateIdentifier) Opens a stream for consuming Events from a single aggregate, allowing the first event to be a Snapshot Event.
AggregateEventStream	openAggregateStream(String aggregateIdentifier, boolean allowSnapshots) Opens a stream for consuming Events from a single aggregate, with given allowSnapshots indicating whether the first Event may be a Snapshot Event.
default AggregateEventStream	openAggregateStream(String aggregateIdentifier, long initialSequence) Opens a stream for consuming Events from a single aggregate, starting with the given initialSequence.
AggregateEventStream	openAggregateStream(String aggregateIdentifier, long initialSequence, long maxSequence) Opens a stream for consuming Events from a single aggregate, starting with the given initialSequence until the given maxSequence.
default EventStream	openStream(long token, int bufferSize) Opens an EventStream, for sequentially consuming events from AxonServer, starting at given token and keeping a local buffer of bufferSize.
default EventStream	openStream(long token, int bufferSize, int refillBatch) Open an EventStream, for sequentially consuming events from AxonServer, starting at given token and keeping a local buffer of bufferSize, which is refilled after consuming refillBatch items.
EventStream	openStream(long token, int bufferSize, int refillBatch, boolean forceReadFromLeader) Open an EventStream, for sequentially consuming events from AxonServer, starting at given token and keeping a local buffer of bufferSize, which is refilled after consuming refillBatch items.
default ResultStream<EventQueryResultEntry>	queryEvents(String queryExpression, boolean liveStream) Queries the Event Store for events using given queryExpression.
default ResultStream<EventQueryResultEntry>	queryEvents(String queryExpression, boolean liveStream, String contextName) Queries the Event Store for events using given queryExpression.
default ResultStream<EventQueryResultEntry>	querySnapshotEvents(String queryExpression, boolean liveStream) Queries the Event Store for snapshot events using given queryExpression.
default ResultStream<EventQueryResultEntry>	querySnapshotEvents(String queryExpression, boolean liveStream, String contextName) Queries the Event Store for snapshot events using given queryExpression.
default CompletableFuture<String>	reschedule(String scheduleToken, Duration triggerDuration, Event event) Convenience method to cancel the scheduled event with given scheduleToken and reschedule the given event to be published after given triggerDuration.
CompletableFuture<String>	reschedule(String scheduleToken, Instant scheduleTime, Event event) Convenience method to cancel the scheduled event with given scheduleToken and reschedule the given event to be published at given scheduleTime.
default CompletableFuture<String>	scheduleEvent(Duration triggerDuration, Event event) Schedule the given event to be published after given triggerDuration.
CompletableFuture<String>	scheduleEvent(Instant scheduleTime, Event event) Schedule the given event to be published at given scheduleTime.
AppendEventsTransaction	startAppendEventsTransaction() Starts a new transaction to append events.

Method Detail

startAppendEventsTransaction

AppendEventsTransaction startAppendEventsTransaction()

Starts a new transaction to append events.

Returns:

The transaction reference onto which to register events to append

scheduleEvent

default CompletableFuture<String> scheduleEvent(Duration triggerDuration,
                                                Event event)

Schedule the given event to be published after given triggerDuration. The returned value can be used to cancel the schedule, or to reschedule the event to another time.

Parameters:

triggerDuration - the amount of time to wait to publish the event

event - the event to publish

Returns:

a token used to cancel the schedule

scheduleEvent

CompletableFuture<String> scheduleEvent(Instant scheduleTime,
                                        Event event)

Schedule the given event to be published at given scheduleTime. The returned value can be used to cancel the schedule, or to reschedule the event to another time.

Parameters:

scheduleTime - The scheduleTime at which to publish the event

event - The event to publish

Returns:

a token used to cancel the schedule

cancelSchedule

CompletableFuture<InstructionAck> cancelSchedule(String scheduleToken)

Cancels the scheduled publication of an event for which the given scheduleToken was returned.

Parameters:

scheduleToken - the token provided when scheduling the event to be cancelled

Returns:

a future reference to the result of the instruction

reschedule

default CompletableFuture<String> reschedule(String scheduleToken,
                                             Duration triggerDuration,
                                             Event event)

Convenience method to cancel the scheduled event with given scheduleToken and reschedule the given event to be published after given triggerDuration. Is effectively the same as cancelling and scheduling in separate calls, but this call requires only a single round-trip to the server.

Parameters:

scheduleToken - the token of the event to cancel

triggerDuration - the point amount of time to wait to publish the event

event - the event to publish

Returns:

a future reference to the token for the new schedule

reschedule

CompletableFuture<String> reschedule(String scheduleToken,
                                     Instant scheduleTime,
                                     Event event)

Convenience method to cancel the scheduled event with given scheduleToken and reschedule the given event to be published at given scheduleTime. Is effectively the same as cancelling and scheduling in separate calls, but this call requires only a single round-trip to the server.

Parameters:

scheduleToken - the token of the event to cancel

scheduleTime - the point in time to publish the new event

event - the event to publish

Returns:

a future reference to the token for the new schedule

appendEvents

default CompletableFuture<Confirmation> appendEvents(Event... events)

Append the given events to the Event Store. Prior to starting, the startAppendEventsTransaction() method should be invoked

Parameters:

events - the Events to append to the Event Store

Returns:

a CompletableFuture resolving the confirmation of the successful processing of the append transaction

findHighestSequence

CompletableFuture<Long> findHighestSequence(String aggregateId)

Find the highest sequence number (i.e. the sequence number of the most recent event) for an aggregate with given aggregateId.

If no events for an aggregate with given identifier have been found, the returned CompletableFuture will resolve to a null value.

Parameters:

aggregateId - the identifier of the aggregate to find the sequence number for

Returns:

a CompletableFuture providing the sequence number found, or resolving to null when no event was found.

openStream

default EventStream openStream(long token,
                               int bufferSize)

Opens an EventStream, for sequentially consuming events from AxonServer, starting at given token and keeping a local buffer of bufferSize. When consuming 1/8th of the buffer size (with a minimum of 16), the client will request additional messages to keep the buffer filled.

A value for bufferSize smaller than 64 items will result in a buffer of 64.

The stream of Events starts immediately upon the invocation of this method, making the first messages available for consumption as soon as they have arrived from AxonServer.

Parameters:

token - the token representing the position to start the stream, or -1 to start from beginning

bufferSize - the number of events to buffer locally

Returns:

the Stream for consuming the requested Events

See Also:

to configure the refill frequency.

openStream

default EventStream openStream(long token,
                               int bufferSize,
                               int refillBatch)

Open an EventStream, for sequentially consuming events from AxonServer, starting at given token and keeping a local buffer of bufferSize, which is refilled after consuming refillBatch items.

A value for bufferSize smaller than 64 items will result in a buffer of 64. A value for refillBatch smaller than 16 will result in a refill batch of 16. A value larger than the bufferSize will be reduced to match the given bufferSize. While this will work, it is not recommended. The refillBatch should be sufficiently small to allow for a constant flow of messages to consume.

The stream of Events starts immediately upon the invocation of this method, making the first messages available for consumption as soon as they have arrived from AxonServer.

Parameters:

token - the token representing the position to start the stream, or -1 to start from beginning

bufferSize - the number of events to buffer locally

refillBatch - the number of events to be consumed prior to refilling the buffer

Returns:

the Stream for consuming the requested Events

See Also:

to use a sensible default for refill batch value.

openStream

EventStream openStream(long token,
                       int bufferSize,
                       int refillBatch,
                       boolean forceReadFromLeader)

Open an EventStream, for sequentially consuming events from AxonServer, starting at given token and keeping a local buffer of bufferSize, which is refilled after consuming refillBatch items. The forceReadFromLeader parameter can be used to enforce this stream to read events from the RAFT leader.

A value for bufferSize smaller than 64 items will result in a buffer of 64. A value for refillBatch smaller than 16 will result in a refill batch of 16. A value larger than the bufferSize will be reduced to match the given bufferSize. While this will work, it is not recommended. The refillBatch should be sufficiently small to allow for a constant flow of messages to consume.

The stream of Events starts immediately upon the invocation of this method, making the first messages available for consumption as soon as they have arrived from AxonServer.

Parameters:

token - the token representing the position to start the stream, or -1 to start from beginning

bufferSize - the number of events to buffer locally

refillBatch - the number of events to be consumed prior to refilling the buffer

forceReadFromLeader - a boolean defining whether Events must be read from the leader

Returns:

the Stream for consuming the requested Events

See Also:

to use a sensible default for refill batch value.

openAggregateStream

default AggregateEventStream openAggregateStream(String aggregateIdentifier)

Opens a stream for consuming Events from a single aggregate, allowing the first event to be a Snapshot Event.

Note that this method does not have any form of flow control. All messages are buffered locally. When expecting large streams of events, consider using openAggregateStream(String, long, long) to retrieve chunks of the event stream instead.

Parameters:

aggregateIdentifier - the identifier of the Aggregate to load events for

Returns:

a stream of Events for the given Aggregate, for which the first event can be a Snapshot Event

openAggregateStream

AggregateEventStream openAggregateStream(String aggregateIdentifier,
                                         boolean allowSnapshots)

Opens a stream for consuming Events from a single aggregate, with given allowSnapshots indicating whether the first Event may be a Snapshot Event. When given allowSnapshots is false, this method will return events starting at the first available sequence number of the aggregate (typically 0).

Note that this method does not have any form of flow control. All messages are buffered locally. When expecting large streams of events, consider using openAggregateStream(String, long, long) to retrieve chunks of the event stream instead.

Parameters:

aggregateIdentifier - the identifier of the Aggregate to load events for

allowSnapshots - a boolean whether to allow a snapshot event as first event, or not

Returns:

a stream of Events for the given Aggregate

openAggregateStream

default AggregateEventStream openAggregateStream(String aggregateIdentifier,
                                                 long initialSequence)

Opens a stream for consuming Events from a single aggregate, starting with the given initialSequence. This method will not return a Snapshot Event as first event.

Note that this method does not have any form of flow control. All messages are buffered locally. When expecting large streams of events, consider using openAggregateStream(String, long, long) to retrieve chunks of the event stream instead.

Parameters:

aggregateIdentifier - the identifier of the Aggregate to load events for

initialSequence - the sequence number of the first event to return

Returns:

a stream of Events for the given Aggregate

openAggregateStream

AggregateEventStream openAggregateStream(String aggregateIdentifier,
                                         long initialSequence,
                                         long maxSequence)

Opens a stream for consuming Events from a single aggregate, starting with the given initialSequence until the given maxSequence. This method will not return a Snapshot Event as first event.

Note: a maxSequence of 0 will result in all events after the initial sequence to be returned.

Parameters:

aggregateIdentifier - the identifier of the Aggregate to load events for

initialSequence - the sequence number of the first event to return

maxSequence - the sequence number of the last event to return

Returns:

a stream of Events for the given Aggregate

appendSnapshot

CompletableFuture<Confirmation> appendSnapshot(Event snapshotEvent)

Store the given snapshotEvent.

Parameters:

snapshotEvent - the Snapshot Event to store

Returns:

a CompletableFuture providing the confirmation upon storage of the snapshot

loadSnapshot

default AggregateEventStream loadSnapshot(String aggregateIdentifier)

Loads the Snapshot Event for the given aggregateIdentifier with the highest sequence number.

Note that the returned stream may not yield any result when there are no snapshots available.

Parameters:

aggregateIdentifier - the identifier of the Aggregate to retrieve snapshots for

Returns:

a stream containing the most recent Snapshot Event

loadSnapshots

default AggregateEventStream loadSnapshots(String aggregateIdentifier,
                                           long maxSequence,
                                           int maxResults)

Loads Snapshot Events for the given aggregateIdentifier with sequence number lower or equal to maxSequence, returning at most maxResults number of snapshots.

Note that Snapshot Events are returned in reverse order of their sequence number.

Parameters:

aggregateIdentifier - the identifier of the Aggregate to retrieve snapshots for

maxSequence - the highest sequence number of snapshots to return

maxResults - the maximum allowed number of snapshots to return

Returns:

a stream containing Snapshot Events within the requested bounds

loadSnapshots

AggregateEventStream loadSnapshots(String aggregateIdentifier,
                                   long initialSequence,
                                   long maxSequence,
                                   int maxResults)

Loads Snapshot Events for the given aggregateIdentifier with sequence number between initialSequence and maxSequence (inclusive), returning at most maxResults number of snapshots.

Note that Snapshot Events are returned in reverse order of their sequence number.

Parameters:

aggregateIdentifier - the identifier of the Aggregate to retrieve snapshots for

initialSequence - the lowest sequence number of snapshots to return

maxSequence - the highest sequence number of snapshots to return

maxResults - the maximum allowed number of snapshots to return

Returns:

a stream containing Snapshot Events within the requested bounds

getLastToken

CompletableFuture<Long> getLastToken()

Retrieves the Token referring to the most recent Event in the Event Store. Using this token to open a stream will only yield events that were appended after execution of this call.

Returns:

a completable future resolving the Token of the last (i.e. most recent) event

getFirstToken

CompletableFuture<Long> getFirstToken()

Retrieves the Token referring to the first Event in the Event Store. Using this token to open a stream will yield all events that available in the event store.

Returns:

a completable future resolving the Token of the first (i.e. oldest) event

getTokenAt

CompletableFuture<Long> getTokenAt(long instant)

Retrieves the token referencing the first Event in the Event Store closest to the given instant.

The timestamp of the referenced Event may be on or after the given instant when the instant occurred within the Event Store's lifecycle. Will return the most recent token when the instant is placed into the future. Will return the earliest token if the instant is placed in the past (read: before the existence of this Event Store).

Using this token to open a stream will yield all events with a timestamp starting at that instance but may also yield events created before this instant, whose append transaction completed after the instant.

Parameters:

instant - The point in time for which to retrieve a token referencing an event within the Event Store. If the given instant resides outside the Event Store its existing time frame, the latest or earliest token is returned for a future or past instant respectively.

Returns:

A completable future resolving the Token of the first (i.e. oldest) event with timestamp on or after given instant.

queryEvents

default ResultStream<EventQueryResultEntry> queryEvents(String queryExpression,
                                                        boolean liveStream)

Queries the Event Store for events using given queryExpression. The given liveStream indicates whether the query should complete when the end of the Event Stream is reached, or if the query should continue processing events as they are stored.

Parameters:

queryExpression - a valid Event Stream Query Language expression

liveStream - whether to continue processing live events

Returns:

a ResultStream containing the query results

queryEvents

default ResultStream<EventQueryResultEntry> queryEvents(String queryExpression,
                                                        boolean liveStream,
                                                        String contextName)

Queries the Event Store for events using given queryExpression. The given liveStream indicates whether the query should complete when the end of the Event Stream is reached, or if the query should continue processing events as they are stored. When a contextName is provided the query is executed for that context, instead of the main context for the channel.

Parameters:

queryExpression - a valid Event Stream Query Language expression

liveStream - whether to continue processing live events

contextName - the name of the context of the event store to query

Returns:

a ResultStream containing the query results

querySnapshotEvents

default ResultStream<EventQueryResultEntry> querySnapshotEvents(String queryExpression,
                                                                boolean liveStream)

Queries the Event Store for snapshot events using given queryExpression. The given liveStream indicates whether the query should complete when the end of the Snapshot Event Stream is reached, or if the query should continue processing snapshot events as they are stored.

Parameters:

queryExpression - a valid Event Stream Query Language expression

liveStream - whether to continue processing live snapshot events

Returns:

a ResultStream containing the query results

querySnapshotEvents

default ResultStream<EventQueryResultEntry> querySnapshotEvents(String queryExpression,
                                                                boolean liveStream,
                                                                String contextName)

Queries the Event Store for snapshot events using given queryExpression. The given liveStream indicates whether the query should complete when the end of the Snapshot Event Stream is reached, or if the query should continue processing snapshot events as they are stored. When a contextName is provided the query is executed for that context, instead of the main context for the channel.

Parameters:

queryExpression - a valid Event Stream Query Language expression

liveStream - whether to continue processing live snapshot events

contextName - the name of the context of the event store to query

Returns:

a ResultStream containing the query results