universum.studios.android.preference

Class SharedPreference<T>

java.lang.Object

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

Type Parameters:

T - Type of the value that can be persisted by this preference implementation.

Direct Known Subclasses:

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

public abstract class SharedPreference<T>
extends Object

Base implementation of shared preference object which may be used to persist a desired value via SharedPreferences and then retrieve it.

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

The key for shared preference must be passed via SharedPreference(String, Object) constructor and may be later obtained via getKey().

Author:

Martin Albedinsky

Nested Class Summary

Nested Classes

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

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	SharedPreference(int keyResId, T defaultValue) Deprecated. Use SharedPreference(String, Object) instead.
protected	SharedPreference(String key, T defValue) Creates a new instance of SharedPreference with the given key and default value.

Method Summary

Modifier and Type	Method and Description
SharedPreference<T>	attachKey(android.content.res.Resources resources) Deprecated. Due to dropped support of keys specified via resource ids, this method becomes obsolete.
android.content.SharedPreferences.OnSharedPreferenceChangeListener	createOnChangeListener(SharedPreference.PreferenceChangeCallback<T> callback) Creates a new instance of SharedPreferences.OnSharedPreferenceChangeListener which may be used to listen for changes in value of this preference within shared preferences.
T	getDefaultValue() Returns the default value of this preference.
String	getKey() Returns the key of this preference.
int	getKeyRes() Deprecated. Use getKey() instead.
T	getValue() Returns the value which is at this time being hold by this preference object.
protected abstract T	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 persist the actual value into the given shared preferences.
boolean	putIntoPreferences(android.content.SharedPreferences preferences) Persists the actual value of this preference into the given shared preferences.
SharedPreference<T>	retrieve(android.content.SharedPreferences preferences) Deprecated. Use getFromPreferences(SharedPreferences) instead.
boolean	save(android.content.SharedPreferences preferences) Deprecated. Use putIntoPreferences(SharedPreferences) instead.
SharedPreference<T>	updateValue(T 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,
                           T 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

@Deprecated
protected SharedPreference(int keyResId,
                                       T defaultValue)

Deprecated. Use SharedPreference(String, Object) instead.

This constructor has been deprecated and will be removed in the next release.

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

@Deprecated
public final int getKeyRes()

Deprecated. Use getKey() instead.

This method has been deprecated and will be removed in the next release.

Return the resource id of the key of this preference.

Returns:

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

attachKey

@Deprecated
public SharedPreference<T> attachKey(android.content.res.Resources resources)

Deprecated. Due to dropped support of keys specified via resource ids, this method becomes obsolete.

This method has been deprecated and will be removed in the next release.

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.

createOnChangeListener

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

Creates a new instance of SharedPreferences.OnSharedPreferenceChangeListener which may be used to listen for changes in value of this preference within shared preferences.

Note, that the created listener will delegate the change event the given callback only in case when the key of changed value matches the key of this preference.

Parameters:

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

Returns:

OnSharedPreferenceListener ready to be used.

See Also:

SharedPreferences.registerOnSharedPreferenceChangeListener(SharedPreferences.OnSharedPreferenceChangeListener), SharedPreferences.unregisterOnSharedPreferenceChangeListener(SharedPreferences.OnSharedPreferenceChangeListener)

getDefaultValue

public final T getDefaultValue()

Returns the default value of this preference.

Returns:

This preference's default value.

See Also:

SharedPreference(String, Object)

updateValue

public SharedPreference<T> updateValue(T newValue)

Updates the actual value of this preference to the given one.

Note, that calling this method does not trigger persisting of the given value into shared preferences.

In order to immediately persist the given new value of this preference into shared preferences, this call need to be followed by putIntoPreferences(SharedPreferences).

Parameters:

newValue - New value for this preference.

Returns:

This preference to allow methods chaining.

See Also:

getValue()

putIntoPreferences

public final boolean putIntoPreferences(android.content.SharedPreferences preferences)

Persists the actual value of this preference into the given shared preferences.

Parameters:

preferences - The instance of shared preferences where should be the actual value of this preference persisted.

Returns:

True if put has been successful, false otherwise.

See Also:

getFromPreferences(SharedPreferences), updateValue(Object), getValue()

onPutIntoPreferences

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

Invoked to persist 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 persisted.

Returns:

True if put has been successful, false otherwise.

getValue

public final T getValue()

Returns the value which is at this time being hold by this preference object.

Note, that this does not need to be necessarily the same value as persisted (if) within shared preferences for this preference if the actual value has been just updated via updateValue(Object) and not persisted via putIntoPreferences(SharedPreferences) or getFromPreferences(SharedPreferences) was not called for this preference yet.

In order to always obtain the actual value of this preference from shared preferences use getFromPreferences(SharedPreferences) instead.

Returns:

The actual value of this preference.

onGetFromPreferences

protected abstract T 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.

retrieve

@Deprecated
public SharedPreference<T> retrieve(android.content.SharedPreferences preferences)

Deprecated. Use getFromPreferences(SharedPreferences) instead.

This method has been deprecated and will be removed in the next release.

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()

save

@Deprecated
public boolean save(android.content.SharedPreferences preferences)

Deprecated. Use putIntoPreferences(SharedPreferences) instead.

This method has been deprecated and will be removed in the next release.

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)