android.content.SharedPreferences Maven / Gradle / Ivy
Show all versions of core Show documentation
/*
* Copyright (C) 2006 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 android.content;
import android.annotation.Nullable;
import java.util.Map;
import java.util.Set;
/**
* Interface for accessing and modifying preference data returned by {@link
* Context#getSharedPreferences}. For any particular set of preferences,
* there is a single instance of this class that all clients share.
* Modifications to the preferences must go through an {@link Editor} object
* to ensure the preference values remain in a consistent state and control
* when they are committed to storage. Objects that are returned from the
* various get methods must be treated as immutable by the application.
*
* Note: This class provides strong consistency guarantees. It is using expensive operations
* which might slow down an app. Frequently changing properties or properties where loss can be
* tolerated should use other mechanisms. For more details read the comments on
* {@link Editor#commit()} and {@link Editor#apply()}.
*
*
Note: This class does not support use across multiple processes.
*
*
* Developer Guides
* For more information about using SharedPreferences, read the
* Data Storage
* developer guide.
*
* @see Context#getSharedPreferences
*/
public interface SharedPreferences {
/**
* Interface definition for a callback to be invoked when a shared
* preference is changed.
*/
public interface OnSharedPreferenceChangeListener {
/**
* Called when a shared preference is changed, added, or removed. This
* may be called even if a preference is set to its existing value.
*
* This callback will be run on your main thread.
*
* @param sharedPreferences The {@link SharedPreferences} that received
* the change.
* @param key The key of the preference that was changed, added, or
* removed.
*/
void onSharedPreferenceChanged(SharedPreferences sharedPreferences, String key);
}
/**
* Interface used for modifying values in a {@link SharedPreferences}
* object. All changes you make in an editor are batched, and not copied
* back to the original {@link SharedPreferences} until you call {@link #commit}
* or {@link #apply}
*/
public interface Editor {
/**
* Set a String value in the preferences editor, to be written back once
* {@link #commit} or {@link #apply} are called.
*
* @param key The name of the preference to modify.
* @param value The new value for the preference. Passing {@code null}
* for this argument is equivalent to calling {@link #remove(String)} with
* this key.
*
* @return Returns a reference to the same Editor object, so you can
* chain put calls together.
*/
Editor putString(String key, @Nullable String value);
/**
* Set a set of String values in the preferences editor, to be written
* back once {@link #commit} or {@link #apply} is called.
*
* @param key The name of the preference to modify.
* @param values The set of new values for the preference. Passing {@code null}
* for this argument is equivalent to calling {@link #remove(String)} with
* this key.
* @return Returns a reference to the same Editor object, so you can
* chain put calls together.
*/
Editor putStringSet(String key, @Nullable Set values);
/**
* Set an int value in the preferences editor, to be written back once
* {@link #commit} or {@link #apply} are called.
*
* @param key The name of the preference to modify.
* @param value The new value for the preference.
*
* @return Returns a reference to the same Editor object, so you can
* chain put calls together.
*/
Editor putInt(String key, int value);
/**
* Set a long value in the preferences editor, to be written back once
* {@link #commit} or {@link #apply} are called.
*
* @param key The name of the preference to modify.
* @param value The new value for the preference.
*
* @return Returns a reference to the same Editor object, so you can
* chain put calls together.
*/
Editor putLong(String key, long value);
/**
* Set a float value in the preferences editor, to be written back once
* {@link #commit} or {@link #apply} are called.
*
* @param key The name of the preference to modify.
* @param value The new value for the preference.
*
* @return Returns a reference to the same Editor object, so you can
* chain put calls together.
*/
Editor putFloat(String key, float value);
/**
* Set a boolean value in the preferences editor, to be written back
* once {@link #commit} or {@link #apply} are called.
*
* @param key The name of the preference to modify.
* @param value The new value for the preference.
*
* @return Returns a reference to the same Editor object, so you can
* chain put calls together.
*/
Editor putBoolean(String key, boolean value);
/**
* Mark in the editor that a preference value should be removed, which
* will be done in the actual preferences once {@link #commit} is
* called.
*
* Note that when committing back to the preferences, all removals
* are done first, regardless of whether you called remove before
* or after put methods on this editor.
*
* @param key The name of the preference to remove.
*
* @return Returns a reference to the same Editor object, so you can
* chain put calls together.
*/
Editor remove(String key);
/**
* Mark in the editor to remove all values from the
* preferences. Once commit is called, the only remaining preferences
* will be any that you have defined in this editor.
*
*
Note that when committing back to the preferences, the clear
* is done first, regardless of whether you called clear before
* or after put methods on this editor.
*
* @return Returns a reference to the same Editor object, so you can
* chain put calls together.
*/
Editor clear();
/**
* Commit your preferences changes back from this Editor to the
* {@link SharedPreferences} object it is editing. This atomically
* performs the requested modifications, replacing whatever is currently
* in the SharedPreferences.
*
*
Note that when two editors are modifying preferences at the same
* time, the last one to call commit wins.
*
*
If you don't care about the return value and you're
* using this from your application's main thread, consider
* using {@link #apply} instead.
*
* @return Returns true if the new values were successfully written
* to persistent storage.
*/
boolean commit();
/**
* Commit your preferences changes back from this Editor to the
* {@link SharedPreferences} object it is editing. This atomically
* performs the requested modifications, replacing whatever is currently
* in the SharedPreferences.
*
*
Note that when two editors are modifying preferences at the same
* time, the last one to call apply wins.
*
*
Unlike {@link #commit}, which writes its preferences out
* to persistent storage synchronously, {@link #apply}
* commits its changes to the in-memory
* {@link SharedPreferences} immediately but starts an
* asynchronous commit to disk and you won't be notified of
* any failures. If another editor on this
* {@link SharedPreferences} does a regular {@link #commit}
* while a {@link #apply} is still outstanding, the
* {@link #commit} will block until all async commits are
* completed as well as the commit itself.
*
*
As {@link SharedPreferences} instances are singletons within
* a process, it's safe to replace any instance of {@link #commit} with
* {@link #apply} if you were already ignoring the return value.
*
*
You don't need to worry about Android component
* lifecycles and their interaction with apply()
* writing to disk. The framework makes sure in-flight disk
* writes from apply() complete before switching
* states.
*
*
The SharedPreferences.Editor interface
* isn't expected to be implemented directly. However, if you
* previously did implement it and are now getting errors
* about missing apply(), you can simply call
* {@link #commit} from apply().
*/
void apply();
}
/**
* Retrieve all values from the preferences.
*
*
Note that you must not modify the collection returned
* by this method, or alter any of its contents. The consistency of your
* stored data is not guaranteed if you do.
*
* @return Returns a map containing a list of pairs key/value representing
* the preferences.
*
* @throws NullPointerException
*/
Map getAll();
/**
* Retrieve a String value from the preferences.
*
* @param key The name of the preference to retrieve.
* @param defValue Value to return if this preference does not exist.
*
* @return Returns the preference value if it exists, or defValue. Throws
* ClassCastException if there is a preference with this name that is not
* a String.
*
* @throws ClassCastException
*/
@Nullable
String getString(String key, @Nullable String defValue);
/**
* Retrieve a set of String values from the preferences.
*
* Note that you must not modify the set instance returned
* by this call. The consistency of the stored data is not guaranteed
* if you do, nor is your ability to modify the instance at all.
*
* @param key The name of the preference to retrieve.
* @param defValues Values to return if this preference does not exist.
*
* @return Returns the preference values if they exist, or defValues.
* Throws ClassCastException if there is a preference with this name
* that is not a Set.
*
* @throws ClassCastException
*/
@Nullable
Set getStringSet(String key, @Nullable Set defValues);
/**
* Retrieve an int value from the preferences.
*
* @param key The name of the preference to retrieve.
* @param defValue Value to return if this preference does not exist.
*
* @return Returns the preference value if it exists, or defValue. Throws
* ClassCastException if there is a preference with this name that is not
* an int.
*
* @throws ClassCastException
*/
int getInt(String key, int defValue);
/**
* Retrieve a long value from the preferences.
*
* @param key The name of the preference to retrieve.
* @param defValue Value to return if this preference does not exist.
*
* @return Returns the preference value if it exists, or defValue. Throws
* ClassCastException if there is a preference with this name that is not
* a long.
*
* @throws ClassCastException
*/
long getLong(String key, long defValue);
/**
* Retrieve a float value from the preferences.
*
* @param key The name of the preference to retrieve.
* @param defValue Value to return if this preference does not exist.
*
* @return Returns the preference value if it exists, or defValue. Throws
* ClassCastException if there is a preference with this name that is not
* a float.
*
* @throws ClassCastException
*/
float getFloat(String key, float defValue);
/**
* Retrieve a boolean value from the preferences.
*
* @param key The name of the preference to retrieve.
* @param defValue Value to return if this preference does not exist.
*
* @return Returns the preference value if it exists, or defValue. Throws
* ClassCastException if there is a preference with this name that is not
* a boolean.
*
* @throws ClassCastException
*/
boolean getBoolean(String key, boolean defValue);
/**
* Checks whether the preferences contains a preference.
*
* @param key The name of the preference to check.
* @return Returns true if the preference exists in the preferences,
* otherwise false.
*/
boolean contains(String key);
/**
* Create a new Editor for these preferences, through which you can make
* modifications to the data in the preferences and atomically commit those
* changes back to the SharedPreferences object.
*
* Note that you must call {@link Editor#commit} to have any
* changes you perform in the Editor actually show up in the
* SharedPreferences.
*
* @return Returns a new instance of the {@link Editor} interface, allowing
* you to modify the values in this SharedPreferences object.
*/
Editor edit();
/**
* Registers a callback to be invoked when a change happens to a preference.
*
*
Caution: The preference manager does
* not currently store a strong reference to the listener. You must store a
* strong reference to the listener, or it will be susceptible to garbage
* collection. We recommend you keep a reference to the listener in the
* instance data of an object that will exist as long as you need the
* listener.
*
* @param listener The callback that will run.
* @see #unregisterOnSharedPreferenceChangeListener
*/
void registerOnSharedPreferenceChangeListener(OnSharedPreferenceChangeListener listener);
/**
* Unregisters a previous callback.
*
* @param listener The callback that should be unregistered.
* @see #registerOnSharedPreferenceChangeListener
*/
void unregisterOnSharedPreferenceChangeListener(OnSharedPreferenceChangeListener listener);
}