public final class

Preferences

extends Object
java.lang.Object
   ↳ com.neomades.preference.Preferences

Class Overview

Object used for modifying application preferences.

Changes are not directly modified to the persistent storage until the save() method is called.

To get a Preferences, call Preferences.getPreferences(String) with the name of preferences.

See Also

Summary

Public Methods
void cancel()
Cancels (rollback) Preferences changes.
boolean contains(String key)
Checks whether the key exists into this Preferences.
boolean exists()
Returns if this Preferences object exists into device application storage.
boolean getBoolean(String key, boolean defaultValue)
Returns the preference values if it exist, or the default value.
boolean getBoolean(String key)
Retrieves a boolean value from the preferences.
byte[] getByteArray(String key)
Retrieves a byte[] value from the preferences.
byte[] getByteArray(String key, byte[] defaultValue)
Retrieves a byte[] value from the preferences.
int getInt(String key, int defaultValue)
Returns the preference values if it exist, or the default value.
int getInt(String key)
Retrieves an integer value from the preferences.
long getLong(String key)
Retrieves an long value from the preferences.
long getLong(String key, long defaultValue)
Returns the preference values if it exist, or the default value.
static Preferences getPreferences(String name)
Retrieve and holds the content of the preferences with the given name.
String getString(String key)
Retrieves an String value from the preferences.
String getString(String key, String defaultValue)
Returns the preference values if it exist, or the default value.
boolean hasChanges()
Returns if this Preferences object contains changes from the persistent store.
void put(String key, String value)
Set a String value in the application preferences, to be written back once save() or cancel() are called.
void put(String key, boolean value)
Set a boolean value in the application preferences, to be written back once save() or cancel() are called.
void put(String key, byte[] value)
Set a byte array in the application preferences, to be written back once save() or cancel() are called.
void put(String key, int value)
Set a int value in the application preferences, to be written back once save() or cancel() are called.
void put(String key, long value)
Set a long value in the application preferences, to be written back once save() or cancel() are called.
void remove(String key)
Deletes from preferences the key entry and its value.
static void removePreferences(String name)
Removes a preference from the application preferences list.
synchronized void save()
Saves (Commit) Preferences changes.
[Expand]
Inherited Methods
From class java.lang.Object

Public Methods

public void cancel ()

Cancels (rollback) Preferences changes.

All modified data (set with put methods) will be cancelled. After calling this method, hasChanges() will return false.

See Also

public boolean contains (String key)

Checks whether the key exists into this Preferences.

Parameters
key the name of the preference entry
Returns
  • true if the preference exists.

public boolean exists ()

Returns if this Preferences object exists into device application storage.

If the Preferences object should exist, then call save() method.

Returns
  • true if the Preferences exists.
See Also

public boolean getBoolean (String key, boolean defaultValue)

Returns the preference values if it exist, or the default value.

The contains(String) method could check if the preference exists.

Parameters
key Name of the preference.
defaultValue Value to return if this preference does not exist.
Returns
  • the preference boolean value if exist, or defaultValue
See Also

public boolean getBoolean (String key)

Retrieves a boolean value from the preferences.

Returns the preference values if it exist, or the default value. The contains(String) method could check if the preference exists.

The call preferences.getBoolean("key") is equivalent to :
preferences.getBoolean("key", false)

Parameters
key Name of the preference.
Returns
  • boolean value (false if it does not exist)
See Also

public byte[] getByteArray (String key)

Retrieves a byte[] value from the preferences.

Parameters
key Name of the preference.
Returns
  • byte array or null

public byte[] getByteArray (String key, byte[] defaultValue)

Retrieves a byte[] value from the preferences.

Parameters
key Name of the preference.
defaultValue the default value if the preference is not found
Returns
  • the byte array or the default value if none

public int getInt (String key, int defaultValue)

Returns the preference values if it exist, or the default value.

The contains(String) method could check if the preference exists.

Parameters
key Name of the preference.
defaultValue Value to return if this preference does not exist.
Returns
  • the preference integer value if exist, or defaultValue
See Also

public int getInt (String key)

Retrieves an integer value from the preferences.

Returns the preference values if it exist, or the default value. The contains(String) method could check if the preference exists.

The call preferences.getInt("key") is equivalent to :
preferences.getInt("key", 0)

Parameters
key Name of the preference.
Returns
  • integer value (0 if it does not exist)
See Also

public long getLong (String key)

Retrieves an long value from the preferences.

Returns the preference values if it exist, or the default value. The contains(String) method could check if the preference exists.

The call preferences.getLong("key") is equivalent to :
preferences.getLong("key", 0)

Parameters
key Name of the preference.
Returns
  • long value (0 if it does not exist)
See Also

public long getLong (String key, long defaultValue)

Returns the preference values if it exist, or the default value.

The contains(String) method could check if the preference exists.

Parameters
key Name of the preference.
defaultValue Value to return if this preference does not exist.
Returns
  • the preference long value if exist, or defaultValue
See Also

public static Preferences getPreferences (String name)

Retrieve and holds the content of the preferences with the given name.

Only one instance of the Preferences is returned for the same name.

If the name does not exist into the persistent storage, then an inexistent and empty preferences object will be returned.

If the preferences object does not exist into the persistent storage, then calling the exists() method will return false. 

 Preferences preferences = Preferences.getPreferences("pref.name");
 boolean exist = preferences.exists();
 // exist has false value here, 
 // because pref.name has never been saved into application storage before.

Parameters
name name of the Preferences object. If the storage does not exist in the device, the storage data will be created after calling the save() method.
Returns
  • the corresponding preferences object (never null)
See Also

public String getString (String key)

Retrieves an String value from the preferences.

Returns the preference values if it exist, or the default value. The contains(String) method could check if the preference exists.

The call preferences.getString("key") is equivalent to :
preferences.getString("key", null)

Parameters
key Name of the preference.
Returns
  • String value (null if it does not exist)
See Also

public String getString (String key, String defaultValue)

Returns the preference values if it exist, or the default value.

The contains(String) method could check if the preference exists.

Parameters
key Name of the preference.
defaultValue Value to return if this preference does not exist.
Returns
  • the preference string value if exist, or defaultValue
See Also

public boolean hasChanges ()

Returns if this Preferences object contains changes from the persistent store.

PutXXXX methods will change this object, this method will return true if save() method has not been called to save any changes.

Returns
  • true if the current changes of the Preferences are saved into persistent storage.
See Also

public void put (String key, String value)

Set a String value in the application preferences, to be written back once save() or cancel() are called. If the key already exists, its current value is replaced with the given value

After calling this method, hasChanges() will return true and the new inserted data is not really saved into application storage. Any change could be saved with the save() method.

Parameters
key The name of the preference to modify.
value The new String value for the preference.
See Also

public void put (String key, boolean value)

Set a boolean value in the application preferences, to be written back once save() or cancel() are called. If the key already exists, its current value is replaced with the given value

After calling this method, hasChanges() will return true and the new inserted data is not really saved into application storage. Any change could be saved with the save() method.

Parameters
key The name of the preference to modify.
value The new boolean value for the preference.
See Also

public void put (String key, byte[] value)

Set a byte array in the application preferences, to be written back once save() or cancel() are called. If the key already exists, its current value is replaced with the given value

After calling this method, hasChanges() will return true and the new inserted data is not really saved into application storage. Any change could be saved with the save() method.

Parameters
key The name of the preference to modify.
value The new byte array for the preference.
See Also

public void put (String key, int value)

Set a int value in the application preferences, to be written back once save() or cancel() are called. If the key already exists, its current value is replaced with the given value

After calling this method, hasChanges() will return true and the new inserted data is not really saved into application storage. Any change could be saved with the save() method.

Parameters
key The name of the preference to modify.
value The new int value for the preference.
See Also

public void put (String key, long value)

Set a long value in the application preferences, to be written back once save() or cancel() are called. If the key already exists, its current value is replaced with the given value

After calling this method, hasChanges() will return true and the new inserted data is not really saved into application storage. Any change could be saved with the save() method.

Parameters
key The name of the preference to modify.
value The new long value for the preference.
See Also

public void remove (String key)

Deletes from preferences the key entry and its value.

Parameters
key key entry to delete

public static void removePreferences (String name)

Removes a preference from the application preferences list.

If a preference with this name does not exist, then nothing is done.

If the preference exists in the persistent storage, it is removed from it permanently.

If the preference object does not exist into the persistent storage (not saved yet), data is also removed.

Parameters
name the name of the preference to remove

public synchronized void save ()

Saves (Commit) Preferences changes.

All modified data (set with put methods) will be saved. After calling this method, hasChanges() will return false.

See Also