public interface

SavedStateRegistry<S>

 androidx.savedstate.SavedStateRegistry<S>

Subclasses:

AbstractSavedStateRegistry<S>, BundleSavedStateRegistry

Gradle dependencies

compile group: 'androidx.savedstate', name: 'savedstate-common', version: '1.0.0-alpha01'

  • groupId: androidx.savedstate
  • artifactId: savedstate-common
  • version: 1.0.0-alpha01

Artifact androidx.savedstate:savedstate-common:1.0.0-alpha01 it located at Google repository (https://maven.google.com/)

Overview

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

Summary

Methods
public java.lang.ObjectconsumeRestoredStateForKey(java.lang.String key)

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

public booleanisRestored()

Returns if a state was restored and can be safely consumed with SavedStateRegistry.consumeRestoredStateForKey(String)

public voidregisterSavedStateProvider(java.lang.String key, SavedStateRegistry.SavedStateProvider<java.lang.Object> savedStateProvider)

Registers a SavedStateRegistry.SavedStateProvider by the given key.

public voidunregisterSavedStateProvider(java.lang.String key)

Unregisters a component previously registered by the given key

Methods

public java.lang.Object consumeRestoredStateForKey(java.lang.String key)

Consumes saved state previously supplied by SavedStateRegistry.SavedStateProvider registered via SavedStateRegistry.registerSavedStateProvider(String, SavedStateRegistry.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. can be used as a signal that a saved state can be safely consumed.

Parameters:

key: a key with which SavedStateRegistry.SavedStateProvider was previously registered.

Returns:

S with the previously saved state or null

public boolean isRestored()

Returns if a state was restored and can be safely consumed with SavedStateRegistry.consumeRestoredStateForKey(String)

Returns:

true if state was restored.

public void registerSavedStateProvider(java.lang.String key, SavedStateRegistry.SavedStateProvider<java.lang.Object> savedStateProvider)

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 SavedStateRegistry.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 java.lang.IllegalArgumentException

Parameters:

key: a key with which returned saved state will be associated
savedStateProvider: savedStateProvider to get saved state.

public void unregisterSavedStateProvider(java.lang.String key)

Unregisters a component previously registered by the given key

Parameters:

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

Source

/*
 * Copyright 2018 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package androidx.savedstate;

import androidx.annotation.MainThread;
import androidx.annotation.NonNull;
import androidx.annotation.Nullable;

/**
 * An interface for plugging components that consumes and contributes to the saved state.
 *
 * @param <S> represents a class for saving a state, typically it is {@link android.os.Bundle}
 */
public interface SavedStateRegistry<S> {
    /**
     * Consumes saved state previously supplied by {@link SavedStateProvider} registered
     * via {@link #registerSavedStateProvider(String, SavedStateProvider)}
     * with the given {@code key}.
     * <p>
     * This call clears an internal reference to returned saved state, so if you call it second time
     * in the row it will return {@code null}.
     * <p>
     * All unconsumed values will be saved during {@code onSaveInstanceState(Bundle savedState)}
     * <p>
     * This method can be called after {@code super.onCreate(savedStateBundle)} of the corresponding
     * component. Calling it before that will result in {@code IllegalArgumentException}.
     * {@link Lifecycle.Event#ON_CREATE} can be used as a signal
     * that a saved state can be safely consumed.
     *
     * @param key a key with which {@link SavedStateProvider} was previously registered.
     * @return {@code S} with the previously saved state or {@code null}
     */
    @MainThread
    @Nullable
    S consumeRestoredStateForKey(@NonNull String key);

    /**
     * Returns if a state was restored and can be safely consumed
     * with {@link #consumeRestoredStateForKey(String)}
     *
     * @return true if state was restored.
     */
    @MainThread
    boolean isRestored();

    /**
     * This interface marks a component that contributes to saved state.
     *
     * @param <S> represents a class for saving a state, typically it is {@link android.os.Bundle}
     */
    interface SavedStateProvider<S> {
        /**
         * Called to retrieve a state from a component before being killed
         * so later the state can be received from {@link #consumeRestoredStateForKey(String)}
         *
         * @return S with your saved state.
         */
        @NonNull
        S saveState();
    }

    /**
     * Registers a {@link SavedStateProvider} by the given {@code key}. This
     * {@code savedStateProvider} will be called
     * during state saving phase, returned object will be associated with the given {@code key}
     * and can be used after the restoration via {@link #consumeRestoredStateForKey(String)}.
     * <p>
     * If there is unconsumed value with the same {@code key},
     * the value supplied by {@code savedStateProvider} will be override and
     * will be written to resulting saved state.
     * <p> if a provider was already registered with the given {@code key}, an implementation should
     * throw an {@link IllegalArgumentException}
     * @param key a key with which returned saved state will be associated
     * @param savedStateProvider savedStateProvider to get saved state.
     */
    @MainThread
    void registerSavedStateProvider(@NonNull String key,
            @NonNull SavedStateProvider<S> savedStateProvider);

    /**
     * Unregisters a component previously registered by the given {@code key}
     *
     * @param key a key with which a component was previously registered.
     */
    @MainThread
    void unregisterSavedStateProvider(@NonNull String key);
}