...

The first use case is user updates of restore progress - In this case users of a Kafka Streams program want to get notification of the progress, reporting status back to UI for example.  The StateRestoreListener set via the KafkaStreams.setStateRestoreListener method will be a global listener.  This means for reporting purposes there will only be one listener reporting on the status for all stores.

The second use case is internal state store management, closing and re-opening a RocksDB instance for bulk loading with different configuration settings for example.  In this case implementors of a custom store want notification of restoration start, progress and ending for state manage purposes.  In this case the StateRestoreListener implementation is  used internally by the given state store.  In this use case users can specify a StateStoreListener per store, but the intent here is not for reporting but for internal state management.  

To use the listener functionality users will implement the StateRestoreListener interface in addition to the StateRestoreCallback or BatchingStateRestoreCallback interfaces when constructing their callbacks.  Providing the callback is still done via the ProcessorContext.register method.  

During the restoration process the type of the restoreCallback is inspected and if it implements the StateRestoreListener then the listener methods are executed.  With this in mind, the StateStoreListener API can be called in two places (although two different implementations); 

1. If the instance level listener is set via the KSteam.setStateRestoreListener method, then that listener will be executed for each poll call.
2. If the provided state-store-level callback extends the StateRestoreListener interface, then those listener methods triggered for each poll call that is restoring that specific store as well.

Compatibility, Deprecation, and Migration Plan

...