de.devland.esperandro.SharedPreferenceActions Maven / Gradle / Ivy
/*
* Copyright 2013 David Kunzler
*
* 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 de.devland.esperandro;
import android.content.Context;
import android.content.SharedPreferences;
import de.devland.esperandro.annotations.GenerateStringResources;
/**
* This interface defines some actions to make the use of Esperandro-generated classes easier without using the
* underlying SharedPreference-instance directly.
*/
public interface SharedPreferenceActions {
/**
* @return the underlying SharedPreference instance.
*/
SharedPreferences get();
/**
* Checks if a value for the given key exists.
*
* @param key the key for the value to be checked
* @return true if the given key exists, false otherwise
*/
boolean contains(String key);
/**
* Removes the value for the given key.
*
* @param key the key for the value to be removed
*/
void remove(String key);
/**
* This method retrieves a saved preference value by name via the content of the given string
* resource.
* It is highly recommended to only use string resource generated by the annotation
* {@link GenerateStringResources} to make sure
* the key exists. If a string unknown to esperandro is provided an {@link UnknownKeyException}
* is thrown.
*
* @param context An Android context to get a string value to the given resource id.
* @param prefId The resource Id of a String that references a preference within the interface extending from this
* class
* @param The type the returned value will be cast to.
* @return The value of the preference.
* @throws UnknownKeyException when a resource Id was given that don't denote a string known to esperandro.
* @throws ClassCastException when the saved preference does not match the desired return type.
*/
V getValue(Context context, int prefId) throws UnknownKeyException;
/**
* This method saved a preference under the key denoted by the given String resource id.
* It is highly recommended to only use string resource generated by the annotation
* {@link GenerateStringResources} to make sure
* the key exists. If a string unknown to esperandro is provided an {@link UnknownKeyException}
* is thrown.
*
* @param context An Android context to get a string value to the given resource id.
* @param prefId The resource Id of a String that references a preference within the interface extending from this
* class
* @param pref The value to be saved in the given preference key.
* @param The type value to be saved.
* @throws UnknownKeyException when a resource Id was given that don't denote a string known to esperandro.
* @throws ClassCastException when the given pref does not match the type of the given preference key.
*/
void setValue(Context context, int prefId, V pref) throws UnknownKeyException;
class UnknownKeyException extends Exception {
private String prefKey;
public UnknownKeyException(String prefKey) {
super(prefKey);
this.prefKey = prefKey;
}
public String getPrefKey() {
return prefKey;
}
}
/**
* Registers a callback to be invoked when a change happens to a preference.
*
* @param listener The callback that will run.
*/
void registerOnChangeListener(SharedPreferences.OnSharedPreferenceChangeListener listener);
/**
* Unregisters a previous callback.
*
* @param listener The callback that should be unregistered.
*/
void unregisterOnChangeListener(SharedPreferences.OnSharedPreferenceChangeListener listener);
/**
* Clears the complete sharedPreferences of the previously given name. (Be aware that ALL preferences under this
* name are cleared not only the ones defined in your interface)
*/
void clearAll();
/**
* Clears all preferences that are defined and generated for this particular interface.
*/
void clearPreferences();
/**
* Initializes the underlying SharedPreference object with the respective explicit or implicit default values. This
* can be useful when the defaults should be shown in the summary in a PreferenceActivity.
*/
void initDefaults();
}