io.pravega.client.stream

Interface ReaderGroup

All Superinterfaces:

java.lang.AutoCloseable, ReaderGroupNotificationListener

public interface ReaderGroup
extends ReaderGroupNotificationListener, java.lang.AutoCloseable

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
void	close() Closes the reader group, freeing any resources associated with it.
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.
java.lang.String	getScope() Returns the scope of the stream which the group is associated with.
java.util.Map<Stream,StreamCut>	getStreamCuts() Returns a stream cut for each stream that this reader group is reading from.
java.util.Set<java.lang.String>	getStreamNames() Returns the set of 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.
void	resetReadersToCheckpoint(Checkpoint checkpoint) Deprecated. Use resetReaderGroup(ReaderGroupConfig) to reset readers to a given Checkpoint.

Methods inherited from interface io.pravega.client.stream.notifications.ReaderGroupNotificationListener

getEndOfDataNotifier, getSegmentNotifier

Method Detail

getMetrics

ReaderGroupMetrics getMetrics()

Returns metrics for this reader group.

Returns:

a ReaderGroupMetrics object for this reader group.

getScope

java.lang.String getScope()

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

Returns:

A scope string

getGroupName

java.lang.String getGroupName()

Returns the name of the group.

Returns:

Reader group name

initiateCheckpoint

java.util.concurrent.CompletableFuture<Checkpoint> initiateCheckpoint(java.lang.String checkpointName,
                                                                      java.util.concurrent.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

@Deprecated
void resetReadersToCheckpoint(Checkpoint checkpoint)

Deprecated. Use resetReaderGroup(ReaderGroupConfig) to reset readers to a given 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.

resetReaderGroup

void resetReaderGroup(ReaderGroupConfig config)

Reset a reader group with the provided 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).

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 .

Parameters:

config - The new configuration for the ReaderGroup.

readerOffline

void readerOffline(java.lang.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

java.util.Set<java.lang.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

java.util.Set<java.lang.String> getStreamNames()

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

Returns:

Set of streams for this group.

getStreamCuts

java.util.Map<Stream,StreamCut> getStreamCuts()

Returns a stream cut for each stream that this reader group is reading from. A stream cut corresponds to a position in the stream, and it can be used by the application as reference to such a position.

Returns:

Map of streams that this group is reading from to the corresponding cuts.

close

void close()

Closes the reader group, freeing any resources associated with it.

Specified by:

close in interface java.lang.AutoCloseable