Module io.axoniq.connector.axonserver
Package io.axoniq.axonserver.connector.event

Interface EventChannel

  • All Known Implementing Classes:
    EventChannelImpl
    public interface EventChannel
    Communication channel for Event related interactions with AxonServer.

    • 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

      • 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

      • createPersistentStream

        CompletableFuture<CreateResult> createPersistentStream​(String streamId,
                                                       PersistentStreamProperties creationProperties)
        Opens the persistent stream identified by streamId. If the stream does not exist it will be created with the properties specified in creationProperties.
        Parameters:
        streamId - the unique identification of a persistent stream
        creationProperties - properties to initialize the persistent stream if it does not exist yet
        Returns:
        a result indicating if the stream has been created or it already existed

      • openPersistentStream

        PersistentStream openPersistentStream​(String streamId,
                                      int bufferSize,
                                      int refillBatch,
                                      PersistentStreamCallbacks callbacks)
        Opens the persistent stream identified by streamId. Fails if the stream does not exist.
        Parameters:
        streamId - the unique identification of a persistent stream
        bufferSize - the number of events to buffer locally
        refillBatch - the number of events to be consumed prior to refilling the buffer
        callbacks - the callbacks that are invoked on persistent stream events
        Returns:
        a PersistedStream streaming events per segment

      • openPersistentStream

        PersistentStream openPersistentStream​(String streamId,
                                      int bufferSize,
                                      int refillBatch,
                                      PersistentStreamCallbacks callbacks,
                                      PersistentStreamProperties creationProperties)
        Opens the persistent stream identified by streamId. If the stream does not exist it will be created with the properties specified in creationProperties.
        Parameters:
        streamId - the unique identification of a persistent stream
        bufferSize - the number of events to buffer locally
        refillBatch - the number of events to be consumed prior to refilling the buffer
        callbacks - the callbacks that are invoked on persistent stream events
        creationProperties - properties to initialize the persistent stream if it does not exist yet
        Returns:
        a PersistentStream streaming events per segment

      • deletePersistentStream

        CompletableFuture<Void> deletePersistentStream​(String streamId)
        Deletes a persistent stream. If the stream does not exist the operation completes successfully.
        Parameters:
        streamId - the unique identification of a persistent stream
        Returns:
        a CompletableFuture that completes when the persistent stream is deleted

      • updatePersistentStreamName

        CompletableFuture<Void> updatePersistentStreamName​(String streamId,
                                                   String streamName)
        Updates the name for a persistent stream.
        Parameters:
        streamId - the unique identification of a persistent stream
        streamName - the new logical name for the stream
        Returns:
        a CompletableFuture that completes when the persistent stream is updated

      • setPersistentStreamSegments

        CompletableFuture<Void> setPersistentStreamSegments​(String streamId,
                                                    int segments)
        Updates the number of segments for a persistent stream.
        Parameters:
        streamId - the unique identification of a persistent stream
        segments - the requested number of segments for the persistent stream
        Returns:
        a CompletableFuture that completes when the persistent stream is updated

      • persistentStreams

        CompletableFuture<List<StreamStatus>> persistentStreams()
        Returns a list of persistent streams with the last confirmed token per segment.
        Returns:
        a list of persistent streams

      • resetPersistentStreamAtHead

        CompletableFuture<Void> resetPersistentStreamAtHead​(String streamId)
        Resets the position of a persistent stream to the head (most recent) event in the event store.
        Parameters:
        streamId - the unique identification of a persistent stream

      • resetPersistentStreamAtTail

        CompletableFuture<Void> resetPersistentStreamAtTail​(String streamId)
        Resets the position of a persistent stream to the first (oldest) event in the event store.
        Parameters:
        streamId - the unique identification of a persistent stream

      • resetPersistentStreamAtPosition

        CompletableFuture<Void> resetPersistentStreamAtPosition​(String streamId,
                                                        long position)
        Resets the position of a persistent stream to the event at given position (global index) in the event store.
        Parameters:
        streamId - the unique identification of a persistent stream
        position - the global index of the first event to be returned

      • resetPersistentStreamAtTime

        CompletableFuture<Void> resetPersistentStreamAtTime​(String streamId,
                                                    long instant)
        Resets the position of a persistent stream to the event at or after the given timestamp in the event store.
        Parameters:
        streamId - the unique identification of a persistent stream
        instant - the timestamp of the first event to be included in the stream