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, LongPreference, StringPreference

public abstract class SharedPreference<T>
extends Object

Base implementation of shared preference object which may be used to persist a desired value in SharedPreferences and later obtain such value.

This class provides API necessary to persist a desired preference value in SharedPreferences via updateValue(Object) followed by putIntoPreferences(SharedPreferences) and to obtain such persisted value from preferences via getFromPreferences(SharedPreferences). The current value that has been obtained from shared preferences for a particular preference may be obtained via getValue().

The key for each shared preference is required to be specified via SharedPreference(String, Object) constructor and may be later obtained via getKey().

Since:

1.0

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(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
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.
T	getValue() Returns the value which is at this time being hold by this preference object.
protected abstract T	onGetFromPreferences(SharedPreferences preferences) Invoked to retrieve the actual value of this preference from the given shared preferences.
protected abstract boolean	onPutIntoPreferences(SharedPreferences preferences) Invoked to persist the actual value into the given shared preferences.
boolean	putIntoPreferences(SharedPreferences preferences) Persists the actual value of this preference into the given shared preferences.
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(@NonNull
                           String key,
                           @Nullable
                           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.

Method Detail

getKey

@NonNull
public final String getKey()

Returns the key of this preference.

Returns:

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

createOnChangeListener

@NonNull
public SharedPreferences.OnSharedPreferenceChangeListener createOnChangeListener(@NonNull
                                                                                          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

@Nullable
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(@Nullable
                                       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(@NonNull
                                        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

@CheckResult
protected abstract boolean onPutIntoPreferences(@NonNull
                                                             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

@Nullable
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

@Nullable
protected abstract T onGetFromPreferences(@NonNull
                                                    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.