io.pravega.client.stream

Interface ReaderGroup

public interface ReaderGroup

A reader group is a collection of readers that collectively read all the events in the stream. The events are distributed among the readers in the group such that each event goes to only one reader. The readers in the group may change over time. Readers are added to the group by calling ClientFactory.createReader(String, String, Serializer, ReaderConfig) and are removed by calling readerOffline(String, Position)

Method Summary

Modifier and Type	Method and Description
String	getGroupName() Returns the name of the group.
ReaderGroupMetrics	getMetrics() Returns metrics for this reader group.
Set<String>	getOnlineReaders() Returns a set of readerIds for the readers that are considered to be online by the group.
String	getScope() Returns the scope of the stream which the group is associated with.
Set<String>	getStreamNames() Returns the set of stream names which was used to configure this group.
CompletableFuture<Checkpoint>	initiateCheckpoint(String checkpointName, ScheduledExecutorService backgroundExecutor) Initiate a checkpoint.
void	readerOffline(String readerId, Position lastPosition) Invoked when a reader that was added to the group is no longer consuming events.
void	resetReadersToCheckpoint(Checkpoint checkpoint) Given a Checkpoint, restore the reader group to the provided checkpoint.
void	updateConfig(ReaderGroupConfig config, Set<String> streamNames) Updates a reader group.

Method Detail

getMetrics

ReaderGroupMetrics getMetrics()

Returns metrics for this reader group.

Returns:

a ReaderGroupMetrics object for this reader group.

getScope

String getScope()

Returns the scope of the stream which the group is associated with.

Returns:

A scope string

getGroupName

String getGroupName()

Returns the name of the group.

Returns:

Reader group name

initiateCheckpoint

CompletableFuture<Checkpoint> initiateCheckpoint(String checkpointName,
                                                 ScheduledExecutorService backgroundExecutor)

Initiate a checkpoint. This causes all readers in the group to receive a special 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, a Checkpoint object will be returned. This can be used to reset the group to this point in the stream by calling resetReadersToCheckpoint(Checkpoint) 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.

Parameters:

checkpointName - The name of the checkpoint (For identification purposes)

backgroundExecutor - A threadPool that can be used to poll for the completion of the checkpoint.

Returns:

A future Checkpoint object that can be used to restore the reader group to this position.

resetReadersToCheckpoint

void resetReadersToCheckpoint(Checkpoint checkpoint)

Given a Checkpoint, restore the reader group to the provided checkpoint. All readers in the group will encounter a ReinitializationRequiredException and when they rejoin the group they will resume from the position the provided checkpoint was taken. (The mapping of segments to readers may not be the same, and the current readers need not be the same ones as existed at the time of the checkpoint.)

Parameters:

checkpoint - The checkpoint to restore to.

updateConfig

void updateConfig(ReaderGroupConfig config,
                  Set<String> streamNames)

Updates a reader group. All existing readers will have to call ClientFactory.createReader(String, String, Serializer, ReaderConfig) . If they continue to read events they will eventually encounter an ReinitializationRequiredException. Readers connecting to the group will start from the point defined in the config, exactly as though it were a new reader group.

Parameters:

config - The configuration for the new ReaderGroup.

streamNames - The name of the streams the reader will read from.

readerOffline

void readerOffline(String readerId,
                   Position lastPosition)

Invoked when a reader that was added to the group is no longer consuming events. This will cause the events that were going to that reader to be redistributed among the other readers. Events after the lastPosition provided will be (re)read by other readers in the ReaderGroup. Note that this method is automatically invoked by EventStreamReader.close()

Parameters:

readerId - The id of the reader that is offline.

lastPosition - The position of the last event that was successfully processed by the reader.

getOnlineReaders

Set<String> getOnlineReaders()

Returns a set of readerIds for the readers that are considered to be online by the group. i.e. ClientFactory.createReader(String, String, Serializer, ReaderConfig) was called but readerOffline(String, Position) was not called subsequently.

Returns:

Set of active reader IDs of the group

getStreamNames

Set<String> getStreamNames()

Returns the set of stream names which was used to configure this group.

Returns:

Set of streams for this group.