SavedStateRegistry

public final class SavedStateRegistry
extends Object

java.lang.Object
   ↳ androidx.savedstate.SavedStateRegistry

An interface for plugging components that consumes and contributes to the saved state.

This objects lifetime is bound to the lifecycle of owning component: when activity or fragment is recreated, new instance of the object is created as well.

Summary

Nested classes

interface SavedStateRegistry.AutoRecreated

Subclasses of this interface will be automatically recreated if they were previously registered via {SavedStateRegistry.runOnNextRecreation(Class)}. 

interface SavedStateRegistry.SavedStateProvider

This interface marks a component that contributes to saved state. 

Public methods

Bundle consumeRestoredStateForKey(String key)

Consumes saved state previously supplied by SavedStateRegistry.SavedStateProvider registered via registerSavedStateProvider(String, SavedStateProvider) with the given key.

boolean isRestored()

Returns if state was restored after creation and can be safely consumed with consumeRestoredStateForKey(String)

void registerSavedStateProvider(String key, SavedStateRegistry.SavedStateProvider provider)

Registers a SavedStateRegistry.SavedStateProvider by the given key.

void runOnNextRecreation(Class<? extends SavedStateRegistry.AutoRecreated> clazz)

Executes the given class when the owning component restarted.

void unregisterSavedStateProvider(String key)

Unregisters a component previously registered by the given key

Inherited methods

Public methods

consumeRestoredStateForKey

public Bundle consumeRestoredStateForKey (String key)

Consumes saved state previously supplied by SavedStateRegistry.SavedStateProvider registered via registerSavedStateProvider(String, SavedStateProvider) with the given key.

This call clears an internal reference to returned saved state, so if you call it second time in the row it will return null.

All unconsumed values will be saved during onSaveInstanceState(Bundle savedState)

This method can be called after super.onCreate(savedStateBundle) of the corresponding component. Calling it before that will result in IllegalArgumentException. Lifecycle.Event.ON_CREATE can be used as a signal that a saved state can be safely consumed.

Parameters
key String: a key with which SavedStateRegistry.SavedStateProvider was previously registered.
Returns
Bundle S with the previously saved state or null

isRestored

public boolean isRestored ()

Returns if state was restored after creation and can be safely consumed with consumeRestoredStateForKey(String)

Returns
boolean true if state was restored.

registerSavedStateProvider

public void registerSavedStateProvider (String key, 
                SavedStateRegistry.SavedStateProvider provider)

Registers a SavedStateRegistry.SavedStateProvider by the given key. This savedStateProvider will be called during state saving phase, returned object will be associated with the given key and can be used after the restoration via consumeRestoredStateForKey(String).

If there is unconsumed value with the same key, the value supplied by savedStateProvider will be override and will be written to resulting saved state.

if a provider was already registered with the given key, an implementation should throw an IllegalArgumentException

Parameters
key String: a key with which returned saved state will be associated
provider SavedStateRegistry.SavedStateProvider: savedStateProvider to get saved state.

runOnNextRecreation

public void runOnNextRecreation (Class<? extends SavedStateRegistry.AutoRecreated> clazz)

Executes the given class when the owning component restarted.

The given class will be automatically instantiated via default constructor and method SavedStateRegistry.AutoRecreated.onRecreated(SavedStateRegistryOwner) will be called. It is called as part of dispatching of Lifecycle.Event.ON_CREATE event.

Parameters
clazz Class: that will need to be instantiated on the next component recreation
Throws
IllegalStateException if you try to call if after Lifecycle.Event.ON_STOP was dispatched

unregisterSavedStateProvider

public void unregisterSavedStateProvider (String key)

Unregisters a component previously registered by the given key

Parameters
key String: a key with which a component was previously registered.