content: /*
   * 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 <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.
       */
      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.
           *
           * <p>This callback will be run on your main thread.
           *
           * <p><em>Note: This callback will not be triggered when preferences are cleared via
           * {@link Editor#clear()}.</em>
           *
           * @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<String> 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.
           * 
           * <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 <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
           * {@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
           * {@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.
       *
       * <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.
       * 
       * @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.
       * 
       * <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.
       * 
       * @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.
       * 
       * <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.
       *
       * <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.
       * 
       * @param listener The callback that should be unregistered.
       * @see #registerOnSharedPreferenceChangeListener
       */
      void unregisterOnSharedPreferenceChangeListener(OnSharedPreferenceChangeListener listener);
  }
  