Interface StateRestoreListener
When calling KafkaStreams.setGlobalStateRestoreListener(StateRestoreListener)
the passed instance is expected to be stateless since the StateRestoreListener is shared across all state
updater threads, of which there is one per stream thread (num.stream.threads).
Users desiring stateful operations will need to provide synchronization internally in
the StateRestoreListener implementation.
Note that this listener is only registered at the per-client level and users can use the storeName
parameter to define specific monitoring for different StateStores.
StateRestoreListener must not be confused with the StateRestoreCallback interface.
The StateRestoreListener is a callback to observe restoration progress.
In contrast, the StateRestoreCallback interface is used by custom state store implementations to provide
the actual state restoration functionality.
Also note that the update process of standby tasks is not monitored via this interface, since a standby task does
not actually restore state, but keeps updating its state from the changelogs written by the active task
which does not ever finish.
The same holds for warm-up tasks, which the runtime runs as standby tasks.
Both are monitored via StandbyUpdateListener instead.
Incremental updates are exposed so users can estimate how much progress has been made.
- See Also:
-
Method Summary
Modifier and TypeMethodDescriptionvoidonBatchRestored(TopicPartition topicPartition, String storeName, long batchEndOffset, long numRestored) Method called after restoring a batch of records.voidonRestoreEnd(TopicPartition topicPartition, String storeName, long totalRestored) Method called when restoring theStateStoreis complete.voidonRestoreStart(TopicPartition topicPartition, String storeName, long startingOffset, long endingOffset) Method called at the very beginning ofStateStorerestoration.default voidonRestoreSuspended(TopicPartition topicPartition, String storeName, long totalRestored) Method called when restoring theStateStoreis suspended before it finished, because the task stopped being an active task on this host: it was assigned elsewhere, demoted to a standby task, or this host is shutting down (the concrete reason is not reported).
-
Method Details
-
onRestoreStart
void onRestoreStart(TopicPartition topicPartition, String storeName, long startingOffset, long endingOffset) Method called at the very beginning ofStateStorerestoration.Called for every active task that begins restoring, including one that has nothing to restore because its local state is already up to date -- a task whose state was just built up as a standby or warm-up task, for instance. In that case
startingOffsetequalsendingOffsetandonRestoreEnd(TopicPartition, String, long)follows with a total of zero records restored, so an empty restoration is told apart by the offsets and the count rather than by the callbacks being skipped.- Parameters:
topicPartition- theTopicPartitioncontaining the values to restorestoreName- the name of the store undergoing restorationstartingOffset- the starting offset of the entire restoration process for thisTopicPartitionendingOffset- the exclusive ending offset of the entire restoration process for thisTopicPartition
-
onBatchRestored
void onBatchRestored(TopicPartition topicPartition, String storeName, long batchEndOffset, long numRestored) Method called after restoring a batch of records. In this case the maximum size of the batch is whatever the value ofmax.poll.recordsis set to.This method is called after restoring each batch and it is advised to keep processing to a minimum. Any heavy processing will block the state updater thread and hold up recovering the next batch, hence slowing down the restore process as a whole. If you need to do any extended processing or connecting to an external service consider doing so asynchronously.
- Parameters:
topicPartition- theTopicPartitioncontaining the values to restorestoreName- the name of the store undergoing restorationbatchEndOffset- the inclusive ending offset for the current restored batch for thisTopicPartitionnumRestored- the total number of records restored in this batch for thisTopicPartition
-
onRestoreEnd
Method called when restoring theStateStoreis complete.- Parameters:
topicPartition- theTopicPartitioncontaining the values to restorestoreName- the name of the store just restoredtotalRestored- the total number of records restored for thisTopicPartition
-
onRestoreSuspended
default void onRestoreSuspended(TopicPartition topicPartition, String storeName, long totalRestored) Method called when restoring theStateStoreis suspended before it finished, because the task stopped being an active task on this host: it was assigned elsewhere, demoted to a standby task, or this host is shutting down (the concrete reason is not reported). If the task becomes an active task on this host again -- assigned back to it, or promoted from the standby task it was demoted to -- anotheronRestoreStart(TopicPartition, String, long, long)would be called.A task whose restoration had already finished, and was reported through
onRestoreEnd(TopicPartition, String, long), is not reported here when it is closed later on. In particular, an active task that had finished restoring and transitioned into theRUNNINGstate and is then demoted to a standby task is not reported here at all; it surfaces only as aStandbyUpdateListener.onUpdateStart(TopicPartition, String, long)for the standby task that replaces it.- Parameters:
topicPartition- theTopicPartitioncontaining the values to restorestoreName- the name of the store just restoredtotalRestored- the total number of records restored for thisTopicPartitionbefore being suspended
-