/*
 * 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 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 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 Editor.commit() and 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 Also:
Context.getSharedPreferences/**
 * 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 <code>get</code> methods must be treated as immutable by the application.
 *
 * <p>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()}.
 *
 * <p><em>Note: This class does not support use across multiple processes.</em>
 *
 * <div class="special reference">
 * <h3>Developer Guides</h3>
 * <p>For more information about using SharedPreferences, read the
 * <a href="{@docRoot}guide/topics/data/data-storage.html#pref">Data Storage</a>
 * developer guide.</p></div>
 *
 * @see Context#getSharedPreferences
 */
public interface SharedPreferences {
    
Interface definition for a callback to be invoked when a shared
preference is changed.
/**
     * 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.
Params:
sharedPreferences – The SharedPreferences that received the change.
key – The key of the preference that was changed, added, or
           removed./**
         * Called when a shared preference is changed, added, or removed. This
         * may be called even if a preference is set to its existing value.
         *
         * <p>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 SharedPreferences object. All changes you make in an editor are batched, and not copied back to the original SharedPreferences until you call commit or apply /**
     * 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 commit or apply are called. 
Params:
key – The name of the preference to modify.
value – The new value for the preference. Passing null for this argument is equivalent to calling remove(String) with this key.
Returns:
Returns a reference to the same Editor object, so you can
chain put calls together./**
         * 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 commit or apply is called. 
Params:
key – The name of the preference to modify.
values – The set of new values for the preference. Passing null for this argument is equivalent to calling remove(String) with this key.
Returns:
Returns a reference to the same Editor object, so you can
chain put calls together./**
         * 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<String> values);
        
        
Set an int value in the preferences editor, to be written back once commit or apply are called. 
Params:
key – The name of the preference to modify.
value – The new value for the preference.
Returns:
Returns a reference to the same Editor object, so you can
chain put calls together./**
         * 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 commit or apply are called. 
Params:
key – The name of the preference to modify.
value – The new value for the preference.
Returns:
Returns a reference to the same Editor object, so you can
chain put calls together./**
         * 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 commit or apply are called. 
Params:
key – The name of the preference to modify.
value – The new value for the preference.
Returns:
Returns a reference to the same Editor object, so you can
chain put calls together./**
         * 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 commit or apply are called. 
Params:
key – The name of the preference to modify.
value – The new value for the preference.
Returns:
Returns a reference to the same Editor object, so you can
chain put calls together./**
         * 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 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.
Params:
key – The name of the preference to remove.
Returns:
Returns a reference to the same Editor object, so you can
chain put calls together./**
         * Mark in the editor that a preference value should be removed, which
         * will be done in the actual preferences once {@link #commit} is
         * called.
         * 
         * <p>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.
Returns:
Returns a reference to the same Editor object, so you can
chain put calls together./**
         * Mark in the editor to remove <em>all</em> values from the
         * preferences.  Once commit is called, the only remaining preferences
         * will be any that you have defined in this editor.
         * 
         * <p>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 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 apply instead. 
Returns:
Returns true if the new values were successfully written
to persistent storage./**
         * 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.
         *
         * <p>Note that when two editors are modifying preferences at the same
         * time, the last one to call commit wins.
         *
         * <p>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 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 commit, which writes its preferences out to persistent storage synchronously, apply commits its changes to the in-memory SharedPreferences immediately but starts an asynchronous commit to disk and you won't be notified of any failures. If another editor on this SharedPreferences does a regular commit while a apply is still outstanding, the commit will block until all async commits are completed as well as the commit itself. 
As SharedPreferences instances are singletons within a process, it's safe to replace any instance of commit with 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 commit from apply().
/**
         * 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.
         *
         * <p>Note that when two editors are modifying preferences at the same
         * time, the last one to call apply wins.
         *
         * <p>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.
         *
         * <p>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.
         *
         * <p>You don't need to worry about Android component
         * lifecycles and their interaction with <code>apply()</code>
         * writing to disk.  The framework makes sure in-flight disk
         * writes from <code>apply()</code> complete before switching
         * states.
         *
         * <p class='note'>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 <code>apply()</code>, you can simply call
         * {@link #commit} from <code>apply()</code>.
         */
        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.
Throws:
NullPointerException – 
Returns:
Returns a map containing a list of pairs key/value representing
the preferences./**
     * Retrieve all values from the preferences.
     *
     * <p>Note that you <em>must not</em> 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<String, ?> getAll();

    
Retrieve a String value from the preferences.
Params:
key – The name of the preference to retrieve.
defValue – Value to return if this preference does not exist.
Throws:
ClassCastException – 
Returns:
Returns the preference value if it exists, or defValue.  Throws
ClassCastException if there is a preference with this name that is not
a String./**
     * 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.
Params:
key – The name of the preference to retrieve.
defValues – Values to return if this preference does not exist.
Throws:
ClassCastException – 
Returns:
Returns the preference values if they exist, or defValues.
Throws ClassCastException if there is a preference with this name
that is not a Set./**
     * Retrieve a set of String values from the preferences.
     * 
     * <p>Note that you <em>must not</em> 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<String> getStringSet(String key, @Nullable Set<String> defValues);
    
    
Retrieve an int value from the preferences.
Params:
key – The name of the preference to retrieve.
defValue – Value to return if this preference does not exist.
Throws:
ClassCastException – 
Returns:
Returns the preference value if it exists, or defValue.  Throws
ClassCastException if there is a preference with this name that is not
an int./**
     * 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.
Params:
key – The name of the preference to retrieve.
defValue – Value to return if this preference does not exist.
Throws:
ClassCastException – 
Returns:
Returns the preference value if it exists, or defValue.  Throws
ClassCastException if there is a preference with this name that is not
a long./**
     * 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.
Params:
key – The name of the preference to retrieve.
defValue – Value to return if this preference does not exist.
Throws:
ClassCastException – 
Returns:
Returns the preference value if it exists, or defValue.  Throws
ClassCastException if there is a preference with this name that is not
a float./**
     * 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.
Params:
key – The name of the preference to retrieve.
defValue – Value to return if this preference does not exist.
Throws:
ClassCastException – 
Returns:
Returns the preference value if it exists, or defValue.  Throws
ClassCastException if there is a preference with this name that is not
a boolean./**
     * 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.
Params:
key – The name of the preference to check.
Returns:
Returns true if the preference exists in the preferences,
        otherwise false./**
     * 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 Editor.commit to have any changes you perform in the Editor actually show up in the SharedPreferences. 
Returns:
Returns a new instance of the Editor interface, allowing you to modify the values in this SharedPreferences object./**
     * 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.
     * 
     * <p>Note that you <em>must</em> 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.
Params:
listener – The callback that will run.
See Also:
unregisterOnSharedPreferenceChangeListener/**
     * Registers a callback to be invoked when a change happens to a preference.
     *
     * <p class="caution"><strong>Caution:</strong> 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.</p>
     *
     * @param listener The callback that will run.
     * @see #unregisterOnSharedPreferenceChangeListener
     */
    void registerOnSharedPreferenceChangeListener(OnSharedPreferenceChangeListener listener);
    
    
Unregisters a previous callback.
Params:
listener – The callback that should be unregistered.
See Also:
registerOnSharedPreferenceChangeListener/**
     * Unregisters a previous callback.
     * 
     * @param listener The callback that should be unregistered.
     * @see #registerOnSharedPreferenceChangeListener
     */
    void unregisterOnSharedPreferenceChangeListener(OnSharedPreferenceChangeListener listener);
}