universum.studios.android.preference

Class SharedPreference<Type>

java.lang.Object

universum.studios.android.preference.SharedPreference<Type>

Type Parameters:

Type - A type of the value that can this implementation of preference hold and manage its saving/obtaining.

Direct Known Subclasses:

ArrayPreference, BooleanPreference, EnumPreference, FloatPreference, IntegerPreference, ListPreference, LongPreference, StringPreference

public abstract class SharedPreference<Type>
extends Object

Base implementation of shared preference object used by PreferencesManager to manage simplified storing and retrieving values from shared preferences.

This class implements API necessary to save its current value into SharedPreferences via updateValue(Object) followed by save(SharedPreferences) and to retrieve such saved value from the preferences via retrieve(SharedPreferences) followed by getValue().

The key for shared preference must be passed during initialization to one of constructors and can be later obtained via getKey() or getKeyRes(). Note, that if you will use resource ids as keys, the raw string key need to be attached via attachKey(Resources), before any initial storing/obtaining.

Author:

Martin Albedinsky

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	SharedPreference.PreferenceChangeCallback<PreferenceType> Callback that can be used to listen for changes in value of a specific SharedPreference implementation.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	SharedPreference(int keyResId, Type defaultValue) Creates a new instance of SharedPreference with the given key resource and default value.
protected	SharedPreference(String key, Type defValue) Creates a new instance of SharedPreference with the given key and default value.

Method Summary

Modifier and Type	Method and Description
SharedPreference<Type>	attachKey(android.content.res.Resources resources) Attaches the key for this preference from the given resources using the current key's resource id specified via SharedPreference(int, Object).
android.content.SharedPreferences.OnSharedPreferenceChangeListener	createOnChangeListener(SharedPreference.PreferenceChangeCallback<Type> callback) Creates new instance of SharedPreferences.OnSharedPreferenceChangeListener which can be used to listen on changes provided up on the value of this preference within shared preferences.
Type	getDefaultValue() Returns the default value of this preference.
String	getKey() Returns the key of this preference.
int	getKeyRes() Return the resource id of the key of this preference.
Type	getValue() Returns the value, which is currently being hold by this preference object.
protected abstract Type	onGetFromPreferences(android.content.SharedPreferences preferences) Invoked to retrieve the actual value of this preference from the given shared preferences.
protected abstract boolean	onPutIntoPreferences(android.content.SharedPreferences preferences) Invoked to save the actual value into the given shared preferences.
SharedPreference<Type>	retrieve(android.content.SharedPreferences preferences) Retrieves the current value of this preference from the given shared preferences.
boolean	save(android.content.SharedPreferences preferences) Saves the current value of this preference into the given shared preferences.
SharedPreference<Type>	updateValue(Type newValue) Updates the actual value of this preference to the given one.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SharedPreference

protected SharedPreference(String key,
                           Type defValue)

Creates a new instance of SharedPreference with the given key and default value.

Parameters:

key - The key under which will be the value of this preference mapped within shared preferences.

defValue - Default value of this preference to return in case, when there is no value saved withing shared preference yet.

Throws:

IllegalArgumentException - If the specified key is empty.

SharedPreference

protected SharedPreference(int keyResId,
                           Type defaultValue)

Creates a new instance of SharedPreference with the given key resource and default value.

Parameters:

keyResId - Resource id of the desired key under which will be the value of this preference mapped within shared preferences.

defaultValue - Default value of this preference for case, when there is no value saved withing shared preference yet.

Throws:

IllegalArgumentException - If the specified keyResId is invalid.

See Also:

attachKey(Resources)

Method Detail

getKey

public final String getKey()

Returns the key of this preference.

Returns:

Same key as passed to SharedPreference(String, Object) constructors.

getKeyRes

public final int getKeyRes()

Return the resource id of the key of this preference.

Returns:

Same resource id as passed to SharedPreference(int, Object) constructor.

attachKey

public SharedPreference<Type> attachKey(android.content.res.Resources resources)

Attaches the key for this preference from the given resources using the current key's resource id specified via SharedPreference(int, Object).

Parameters:

resources - An application's resources to obtain key.

Returns:

This preference to allow methods chaining.

Throws:

IllegalArgumentException - If key obtained from the resources for the resource id is empty.

getDefaultValue

public final Type getDefaultValue()

Returns the default value of this preference.

Returns:

Same value as passed to SharedPreference(String, Object).

retrieve

public SharedPreference<Type> retrieve(android.content.SharedPreferences preferences)

Retrieves the current value of this preference from the given shared preferences.

Parameters:

preferences - The instance of shared preferences into which was the value of this preference before saved.

Returns:

This preference to allow methods chaining.

See Also:

getValue()

onGetFromPreferences

protected abstract Type onGetFromPreferences(android.content.SharedPreferences preferences)

Invoked to retrieve the actual value of this preference from the given shared preferences.

Parameters:

preferences - The instance of shared preferences into which was the value of this preference before saved.

Returns:

The actual value of this preference from the given shared preferences.

save

public boolean save(android.content.SharedPreferences preferences)

Saves the current value of this preference into the given shared preferences.

Parameters:

preferences - The instance of shared preferences into which will be the current value of this preference saved.

Returns:

True if saving operation succeed, false otherwise.

See Also:

updateValue(Object)

onPutIntoPreferences

protected abstract boolean onPutIntoPreferences(android.content.SharedPreferences preferences)

Invoked to save the actual value into the given shared preferences.

Parameters:

preferences - The instance of shared preferences into which should be the current value of this preference saved.

Returns:

True if saving operation succeed, false otherwise.

createOnChangeListener

public android.content.SharedPreferences.OnSharedPreferenceChangeListener createOnChangeListener(SharedPreference.PreferenceChangeCallback<Type> callback)

Creates new instance of SharedPreferences.OnSharedPreferenceChangeListener which can be used to listen on changes provided up on the value of this preference within shared preferences.

Note, that here created listener will fire the given callback only in case, that the key received in the callback from shared preferences will match the key of this preference.

Parameters:

callback - Callback to be invoked when the value of this preference changes.

Returns:

New instance of OnSharedPreferenceListener.

See Also:

SharedPreferences

getValue

public final Type getValue()

Returns the value, which is currently being hold by this preference object. Note, that this isn't current value from shared preferences if this preference wasn't parsed or retrieve(SharedPreferences)) before this call.

To obtain always an actual value from shared preferences, perform this calls on the instance of SharedPreference of which value you want to obtain:

  <b>SharedPreference.parse(SharedPreferences).getActualValue()</b> or
  <b>SharedPreference.parse(PreferencesManager).getActualValue()</b>
 

Returns:

The actual value of this preference or null if this preference's key is invalid.

See Also:

retrieve(SharedPreferences)

updateValue

public SharedPreference<Type> updateValue(Type newValue)

Updates the actual value of this preference to the given one. Note, that this doesn't updates the value within shared preferences.

To immediately save the given new value of this preference into shared preferences, perform this calls on the instance of SharedPreference of which value you want to save:

  <b>SharedPreference.updateValue(Type).save(SharedPreferences)</b> or
  <b>SharedPreference.updateValue(Type).save(PreferencesManager)</b>
 

Parameters:

newValue - New value for this preference.

Returns:

This preference to allow methods chaining.

See Also:

save(SharedPreferences)