/// <summary>
/// Same type of query as <see cref="EventsByTag"/> but the event stream
/// is completed immediately when it reaches the end of the "result set". Events that are
/// stored after the query is completed are not included in the event stream.
/// </summary>
public Source <EventEnvelope, NotUsed> CurrentEventsByTag(string tag, Offset offset = null)
{
offset = offset ?? new Sequence(StreamPosition.Start);
switch (offset)
{
case Sequence seq:
var props = EventsByTagPublisher.Props(
tag,
false,
seq.Value,
long.MaxValue,
_maxBufferSize,
_writeJournalPluginId
);
return(Source.ActorPublisher <EventEnvelope>(props)
.MapMaterializedValue(_ => NotUsed.Instance)
.Named($"CurrentEventsByTag-{tag}"));
case NoOffset _:
return(CurrentEventsByTag(tag, new Sequence(StreamPosition.Start)));
default:
throw new ArgumentException($"SqlReadJournal does not support {offset.GetType().Name} offsets");
}
}
/// <summary>
/// <see cref="EventsByTag"/> is used for retrieving events that were marked with
/// a given tag, e.g. all events of an Aggregate Root type.
/// <para></para>
/// To tag events you create an <see cref="IEventAdapter"/> that wraps the events
/// in a <see cref="Tagged"/> with the given `tags`.
/// <para></para>
/// You can use <see cref="NoOffset"/> to retrieve all events with a given tag or retrieve a subset of all
/// events by specifying a <see cref="Sequence"/>. The `offset` corresponds to an ordered sequence number for
/// the specific tag. Note that the corresponding offset of each event is provided in the
/// <see cref="EventEnvelope"/>, which makes it possible to resume the
/// stream at a later point from a given offset.
/// <para></para>
/// The `offset` is exclusive, i.e. the event with the exact same sequence number will not be included
/// in the returned stream.This means that you can use the offset that is returned in <see cref="EventEnvelope"/>
/// as the `offset` parameter in a subsequent query.
/// <para></para>
/// In addition to the <paramref name="offset"/> the <see cref="EventEnvelope"/> also provides `persistenceId` and `sequenceNr`
/// for each event. The `sequenceNr` is the sequence number for the persistent actor with the
/// `persistenceId` that persisted the event. The `persistenceId` + `sequenceNr` is an unique
/// identifier for the event.
/// <para></para>
/// The returned event stream is ordered by the offset (tag sequence number), which corresponds
/// to the same order as the write journal stored the events. The same stream elements (in same order)
/// are returned for multiple executions of the query. Deleted events are not deleted from the
/// tagged event stream.
/// <para></para>
/// The stream is not completed when it reaches the end of the currently stored events,
/// but it continues to push new events when new events are persisted.
/// Corresponding query that is completed when it reaches the end of the currently
/// stored events is provided by <see cref="CurrentEventsByTag"/>.
/// <para></para>
/// The SQL write journal is notifying the query side as soon as tagged events are persisted, but for
/// efficiency reasons the query side retrieves the events in batches that sometimes can
/// be delayed up to the configured `refresh-interval`.
/// <para></para>
/// The stream is completed with failure if there is a failure in executing the query in the
/// backend journal.
/// </summary>
public Source <EventEnvelope, NotUsed> EventsByTag(string tag, Offset offset = null)
{
offset = offset ?? new Sequence(0L);
switch (offset)
{
case Sequence seq:
return(Source.ActorPublisher <EventEnvelope>(EventsByTagPublisher.Props(tag, seq.Value, long.MaxValue, _refreshInterval, _maxBufferSize, _writeJournalPluginId))
.MapMaterializedValue(_ => NotUsed.Instance)
.Named($"EventsByTag-{tag}"));
case NoOffset _:
return(EventsByTag(tag, new Sequence(0L)));
default:
throw new ArgumentException($"{GetType().Name} does not support {offset.GetType().Name} offsets");
}
}
