public interface ReaderGroup extends ReaderGroupNotificationListener, java.lang.AutoCloseable
EventStreamClientFactory.createReader(String, String, Serializer, ReaderConfig)
and are removed by calling readerOffline(String, Position)
Modifier and Type | Method and Description |
---|---|
void |
close()
Closes the reader group, freeing any resources associated with it.
|
java.util.concurrent.CompletableFuture<java.util.Map<Stream,StreamCut>> |
generateStreamCuts(java.util.concurrent.ScheduledExecutorService backgroundExecutor)
Generates a
StreamCut after co-ordinating with all the readers using
StateSynchronizer . |
java.lang.String |
getGroupName()
Returns the name of the group.
|
ReaderGroupMetrics |
getMetrics()
Returns metrics for this reader group.
|
java.util.Set<java.lang.String> |
getOnlineReaders()
Returns a set of readerIds for the readers that are considered to be online by the group.
|
ReaderSegmentDistribution |
getReaderSegmentDistribution()
Returns current distribution of number of segments assigned to each reader in the reader group.
|
java.lang.String |
getScope()
Returns the scope of the stream which the group is associated with.
|
java.util.Map<Stream,StreamCut> |
getStreamCuts()
Returns a
StreamCut for each stream that this reader group is reading from. |
java.util.Set<java.lang.String> |
getStreamNames()
Returns the set of scoped stream names which was used to configure this group.
|
java.util.concurrent.CompletableFuture<Checkpoint> |
initiateCheckpoint(java.lang.String checkpointName,
java.util.concurrent.ScheduledExecutorService backgroundExecutor)
Initiate a checkpoint.
|
void |
readerOffline(java.lang.String readerId,
Position lastPosition)
Invoked when a reader that was added to the group is no longer consuming events.
|
void |
resetReaderGroup(ReaderGroupConfig config)
Reset a reader group with the provided
ReaderGroupConfig . |
getEndOfDataNotifier, getSegmentNotifier
ReaderGroupMetrics getMetrics()
java.lang.String getScope()
java.lang.String getGroupName()
java.util.concurrent.CompletableFuture<Checkpoint> initiateCheckpoint(java.lang.String checkpointName, java.util.concurrent.ScheduledExecutorService backgroundExecutor)
EventRead
that contains the provided checkpoint name. This can be used to provide an
indication to them that they should persist their state. Once all of the readers have
received the notification and resumed reading the future will return a Checkpoint
object which contains the StreamCut of the reader group at the time they received the
checkpoint. This can be used to reset the group to this point in the stream by calling
resetReaderGroup(ReaderGroupConfig)
if the checkpoint fails or the result cannot be
obtained an exception will be set on the future.
This method can be called and a new checkpoint can be initiated while another is still in
progress if they have different names. If this method is is called again before the
checkpoint has completed with the same name the future returned to the second caller will
refer to the same checkpoint object as the first.checkpointName
- The name of the checkpoint (For identification purposes)backgroundExecutor
- A threadPool that can be used to poll for the completion of the
checkpoint.void resetReaderGroup(ReaderGroupConfig config)
ReaderGroupConfig
.
- The stream(s) that are part of the reader group
can be specified using ReaderGroupConfig.ReaderGroupConfigBuilder.stream(String)
,
ReaderGroupConfig.ReaderGroupConfigBuilder.stream(String, StreamCut)
and
ReaderGroupConfig.ReaderGroupConfigBuilder.stream(String, StreamCut, StreamCut)
.
- To reset a reader group to a given checkpoint use
ReaderGroupConfig.ReaderGroupConfigBuilder.startFromCheckpoint(Checkpoint)
api.
- To reset a reader group to a given StreamCut use
ReaderGroupConfig.ReaderGroupConfigBuilder.startFromStreamCuts(Map)
.
EventStreamClientFactory.createReader(String, String, Serializer, ReaderConfig)
.
If they continue to read events they will eventually encounter an ReinitializationRequiredException
.config
- The new configuration for the ReaderGroup.void readerOffline(java.lang.String readerId, Position lastPosition)
ReaderGroup
.
Note that this method is automatically invoked by EventStreamReader.close()
readerId
- The id of the reader that is offline.lastPosition
- The position of the last event that was successfully processed by the
reader.java.util.Set<java.lang.String> getOnlineReaders()
EventStreamClientFactory.createReader(String, String, Serializer, ReaderConfig)
was called but readerOffline(String, Position)
was not called subsequently.java.util.Set<java.lang.String> getStreamNames()
java.util.Map<Stream,StreamCut> getStreamCuts()
StreamCut
for each stream that this reader group is reading from.
The stream cut corresponds to the last checkpointed read offsets of the readers, and
it can be used by the application as reference to such a position.
A more precise StreamCut
, with the latest read offsets can be obtained using
generateStreamCuts(ScheduledExecutorService)
API.@Beta java.util.concurrent.CompletableFuture<java.util.Map<Stream,StreamCut>> generateStreamCuts(java.util.concurrent.ScheduledExecutorService backgroundExecutor)
StreamCut
after co-ordinating with all the readers using
StateSynchronizer
. A StreamCut
is
generated by using the latest segment read offsets returned by the readers
along with unassigned segments (if any).
The configuration ReaderGroupConfig.groupRefreshTimeMillis
decides
the maximum delay by which the readers return the latest read offsets of their
assigned segments.
The StreamCut
generated by this API can be used by the application as a
reference to a position in the stream. This is guaranteed to be greater than or
equal to the position of the readers at the point of invocation of the API. The
StreamCut
s generated can be used to perform bounded processing of the Stream
by configuring a ReaderGroup
with a ReaderGroupConfig
where the
StreamCut
s are specified as the lower bound and/or upper bounds using the
apis
ReaderGroupConfig.ReaderGroupConfigBuilder.stream(Stream, StreamCut, StreamCut)
or ReaderGroupConfig.ReaderGroupConfigBuilder.stream(Stream, StreamCut)
or
ReaderGroupConfig.ReaderGroupConfigBuilder.startFromStreamCuts(Map)
.
Note: Generating a precise StreamCut
, for example a StreamCut
pointing to
end of Q1 across all segments, is difficult as it depends on the configuration
ReaderGroupConfig.groupRefreshTimeMillis
which decides the duration by
which all the readers running on different machines/ processes respond with their
latest read offsets. Hence, the StreamCut
would point to a position in the
Stream
which might include events from Q2. The application thus would need to
filter out such additional events.
backgroundExecutor
- A thread pool that will be used to poll if the
positions from all the readers have been fetched.ReaderSegmentDistribution getReaderSegmentDistribution()
void close()
close
in interface java.lang.AutoCloseable