danger.app
Class SettingsDB

java.lang.Object
  danger.app.Listener
      danger.app.SettingsDB

Direct Known Subclasses:

CategoryDB

public class SettingsDB
extends Listener

Application interface to the SettingsDB class. This class can be used to manage setting values, if they are key value pairs. A setting key is a string, and cannot be longer than 128 characters. A setting value may be an integer, string, or a byte array. The keys of a SettingsDB need to be unique and are matched case-sensitively. Each key and value pair is stored in the record field of a DataStore. The SettingsDB has a corresponding DataStore on the device. Since DataStores can be autosync'ed with the service, instances of this class can be autosync'ed as well. SettingsDB is the recommended way to use a DataStore. Accessing it directly is bad idea unless you truly know what it is you are doing (only few can make that claim)

Note that SettingsDB namespaces are local to an application, and one application cannot open another applications SettingsDB.

NOTE: The exception-throwing behavior of this class is a bit inconsistent (for historical reasons, not by intentional design). The two methods named getStringValue() return null when handed a key/index that isn't found or is of the wrong type, but the other get*() methods throw SettingsDBException.

Currently, the contents of each record in the DataStore will look like this:

 ===========================================================================
 | type | key length |     key      |           Data                       |
 ===========================================================================
    1B        1B          max 128B              variable

The type and key size are both one byte only (which is why the key is limited in length).

Field Summary

static int	DATA_TYPE_BYTES
static int	DATA_TYPE_INTEGER
static int	DATA_TYPE_STRING
protected static boolean	DEBUG_CONFLICT_RESOLVE
protected static boolean	DEBUG_CONFLICT_RESOLVE_VERBOSE
protected static boolean	DEBUG_SORT
protected static int	DEFAULT_SETTING
protected static boolean	IS_DEBUG
protected Listener	mAutoSyncNotifyee Deprecated.
protected DataStore	mDataStore Deprecated.

Constructor Summary

SettingsDB(String dbName)
Create or get a SettingsDB.

SettingsDB(String dbName, boolean autoSync)
Create or get a SettingsDB.

Method Summary

void	clearAll() Remove all records in a settings database.
void	dump() Dump the contents of the settings database to debug output.
int	find(String inKey) Find and return the index for a record in the database.
protected int	find2(String inKey) Find and return the index for a record in the database.
static boolean	findDB(String dbName) Find a settings database.
static boolean	findDB(String dbName, boolean absolutePath) Find a settings database.
byte[]	getBytes(int i) Get byte array specifed by index.
byte[]	getBytes(String inKey) Get byte array specifed by key.
int	getDataType(int i) Get the data type of the ith entry in a settings database.
int	getIntValue(int i) Get integer value specifed by index.
int	getIntValue(String inKey) Get integer value specifed by key.
String	getKey(int i) Get a specific key from a settings database.
int	getNumEntries() Get the number of records in a settings database.
void	getObject(String inKey, Storable ioObject) Get object specifed by key.
String	getStringValue(int i) Get string value specifed by index.
String	getStringValue(String inKey) Get string value specifed by key.
boolean	receiveEvent(Event e) Receive a SettingsDB-related event.
void	registerAutoSyncBundleListener(Bundle bundle) register autosync listener with datastore Registers with datastore the autosync listener and the datastore's owner bundle.
String	remove(String inKey) Remove the record specifed by key.
boolean	renameKey(int i, String newKey) Rename a specific key in a settings database.
boolean	renameKey(String oldKey, String newKey) Rename a specific key in a settings database.
protected void	resolveAllRecords() Resolves each record with every other record in the settings database.
protected void	resolveAutoSyncConflicts() Resolves potential conflicts caused by auto-syncing the data from Danger service.
void	setAutoSyncNotifyee(Listener inNotifyee) Set the Listener for AutoSync events.
void	setBytes(String inKey, byte[] inValue) Set the byte array specifed by key.
void	setBytes(String inKey, byte[] inValue, boolean isDefault) Set the byte array specifed by key.
void	setIntValue(String inKey, int inValue) Set the integer value specifed by key.
void	setIntValue(String inKey, int inValue, boolean isDefault) Set the integer value specifed by key.
void	setObject(String inKey, Storable inObject) Set the object specifed by key.
void	setObject(String inKey, Storable inObject, boolean isDefaultSetting) Set the object specifed by key.
void	setStringValue(String inKey, String inValue) Set the string value specifed by key.
void	setStringValue(String inKey, String inValue, boolean isDefault) Set the string value specifed by key.
protected void	sort() Sort the settings database by the keys.

Methods inherited from class danger.app.Listener

cancelEvents, childEventPump, childEventPumpDone, eventProblem, isDispatchingThread, receiveEventInternal, sendEvent, sendEvent, sendEvent, sendEvent, sendEvent, sendLowPriorityEvent

Methods inherited from class java.lang.Object

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

Field Detail

mDataStore

protected DataStore mDataStore

Deprecated.

mAutoSyncNotifyee

protected Listener mAutoSyncNotifyee

Deprecated.

DATA_TYPE_INTEGER

public static final int DATA_TYPE_INTEGER

See Also:

Constant Field Values

DATA_TYPE_STRING

public static final int DATA_TYPE_STRING

See Also:

Constant Field Values

DATA_TYPE_BYTES

public static final int DATA_TYPE_BYTES

See Also:

Constant Field Values

DEFAULT_SETTING

protected static final int DEFAULT_SETTING

See Also:

Constant Field Values

IS_DEBUG

protected static final boolean IS_DEBUG

See Also:

Constant Field Values

DEBUG_CONFLICT_RESOLVE

protected static final boolean DEBUG_CONFLICT_RESOLVE

See Also:

Constant Field Values

DEBUG_CONFLICT_RESOLVE_VERBOSE

protected static final boolean DEBUG_CONFLICT_RESOLVE_VERBOSE

See Also:

Constant Field Values

DEBUG_SORT

protected static final boolean DEBUG_SORT

See Also:

Constant Field Values

Constructor Detail

SettingsDB

public SettingsDB(String dbName,
                  boolean autoSync)

Create or get a SettingsDB. Used to create or retrieve a settings database. If a database with the name dbName is found, it is returned. If not, a new database is constructed. Use the findDB method to determine whether a database with the specified name exists before assuming you can use it. The autoSync parameter is true if the settings database should be automatically backed up to the service.

Parameters:

dbName - A String specifying the name of the settings database.

autoSync - A boolean that is true if the database is to be backed up to the service.

SettingsDB

public SettingsDB(String dbName)

Create or get a SettingsDB. Used to create or retrieve a settings database. If a database with the name dbName is found, it is returned. If not, a new database is constructed. Use the findDB method to determine whether a database with the specified name exists before assuming you can use it. The settings database is NOT synchronized with the service.

Parameters:

dbName - A String specifying the name of the settings database.

Method Detail

receiveEvent

public boolean receiveEvent(Event e)

Receive a SettingsDB-related event. SettingsDB is a listener, and can receive events. It currently handles EventType.EVENT_DATASTORE_RESTORED event.

Overrides:

receiveEvent in class Listener

Parameters:

e - An Event object containing the event type and data.

Returns:

A boolean that is true if the method handled the event.

findDB

public static boolean findDB(String dbName)

Find a settings database. Searches the data store for a settings database with the specified name. Returns true is one is found.

Parameters:

dbName - A String specifying the name of the database to be found.

Returns:

A boolean that is true if the database was found.

findDB

public static boolean findDB(String dbName,
                             boolean absolutePath)

Find a settings database. Searches the data store for a settings database with the specified name. Returns true is one is found.

Parameters:

dbName - A String specifying the name of the database to be found.

Returns:

A boolean that is true if the database was found.

getNumEntries

public int getNumEntries()

Get the number of records in a settings database. Returns the number of records stored in a settings database.

Returns:

the number of records stored in the database.

getDataType

public int getDataType(int i)

Get the data type of the ith entry in a settings database. Returns the data type for the item stored at index i. The index is zero-based. The data type can be of integer, string, or byte array.

Parameters:

i - An int specifying the index of the record to be retrieved.

Returns:

An int specifying the data type for the record.

getKey

public String getKey(int i)

Get a specific key from a settings database. Returns the key for the item stored at index i. The index is zero-based. This method is useful for looping through all the records in a database. Each record is stored as a key followed by a value.

Parameters:

i - An int specifying the index of the record to be retrieved.

Returns:

A String specifying the key for the record.

renameKey

public boolean renameKey(String oldKey,
                         String newKey)

Rename a specific key in a settings database. Renames the key specified by oldKey to the key specified by newKey. Returns true if the key is successfully renamed or false if oldKey is not found. Also causes the settings database to be resorted.

Parameters:

oldKey - A String specifying the name of the key to be renamed.

newKey - A String specifying the new name for the key.

Returns:

A boolean that is true if the key was found and renamed successfully.

renameKey

public boolean renameKey(int i,
                         String newKey)

Rename a specific key in a settings database. Renames the key found at index i to the key specified by newKey. The index i is zero-based. Also causes the settings database to be re-sorted.

Parameters:

i - An int specifying the index to the key to be renamed.

newKey - A String specifying the new name for the key.

Returns:

A boolean that is true if the key was found and renamed successfully.

find

public int find(String inKey)

Find and return the index for a record in the database. Searches the database for a record with a key matching inKey, then returns the associated index. Returns -1 if no matching key is found.

Parameters:

inKey - A String specifying the key for the record.

Returns:

-1 or the index of the key.

find2

protected int find2(String inKey)

Find and return the index for a record in the database. Searches the database for a record with a key matching inKey, then returns the associated index. If no matching key is found, it returns the index for which inKey can be inserted after, for sorting the keys in alphebetical order.

Parameters:

inKey - A String specifying the key for the record.

Returns:

-1 or the index of the key.

sort

protected void sort()

Sort the settings database by the keys. Sort the settings database by the keys. The sort is done by alphebetical order.

dump

public void dump()

Dump the contents of the settings database to debug output. Dump the contents of the settings database to debug output.

clearAll

public void clearAll()

Remove all records in a settings database. Removes all records from a settings database.

getIntValue

public int getIntValue(String inKey)
                throws SettingsDBException

Get integer value specifed by key. Returns the integer value associated with the key specified by inKey. If no record is found with the key specified by inKey, a SettingsDBException is thrown.

Parameters:

inKey - non-null; the key to look up

Returns:

An int containing the value associated with the specified key.

Throws:

NullPointerException - thrown if inKey is null

IllegalArgumentException - thrown if inKey is non-null but otherwise invalid

SettingsDBException - thrown if the record is not found or is of the wrong type

getIntValue

public int getIntValue(int i)
                throws SettingsDBException

Get integer value specifed by index. Returns the integer value associated with the record specified by index i. If no record exists at index i, a SettingsDBException is thrown.

Parameters:

i - An int specifying the index to the record to be found.

Returns:

An int containing the value associated with the specified record.

Throws:

SettingsDBException - thrown if the record is not found or is of the wrong type

setIntValue

public void setIntValue(String inKey,
                        int inValue)

Set the integer value specifed by key. Sets the integer value associated with the key specified by inKey to inValue. If no record is found with the key specified by inKey, a new record is created. If a record is found, its value is updated.

Parameters:

inKey - non-null; the key to look up

inValue - An int containing the value to be associated with the key.

Throws:

NullPointerException - thrown if inKey is null

IllegalArgumentException - thrown if inKey is non-null but otherwise invalid

setIntValue

public void setIntValue(String inKey,
                        int inValue,
                        boolean isDefault)

Set the integer value specifed by key. Sets the integer value associated with the key specified by inKey to inValue. If no record is found with the key specified by inKey, a new record is created. If a record is found, its value is updated. The isDefault flag is used when records are synchronized with the service. It lets the server know whether the setting was specified by a user, or is just the default for the program. A better way to handle this is not to store the default settings at all. If no entry is found in the database, use the default value stored in your code. If an entry is found, assume it was specified by the user.

Parameters:

inKey - non-null; the key to look up

inValue - An int containing the value to be associated with the key.

isDefault - A boolean that is true if the value was not specified by the user.

Throws:

NullPointerException - thrown if inKey is null

IllegalArgumentException - thrown if inKey is non-null but otherwise invalid

getStringValue

public String getStringValue(String inKey)

Get string value specifed by key. Returns the string value associated with the key specified by inKey. If no record is found with the key specified by inKey, this method returns null.

Parameters:

inKey - non-null; the key to look up

Returns:

null-ok; the string value associated with the specified key, or null if the key was not found or is not of the right type

Throws:

NullPointerException - thrown if inKey is null

IllegalArgumentException - thrown if inKey is non-null but otherwise invalid

getStringValue

public String getStringValue(int i)

Get string value specifed by index. Returns the string value associated with the record specified by index i.

Parameters:

i - An int specifying the index to the record to be found.

Returns:

null-ok; the string value associated with the specified key, or null if the key was not found or is not of the right type

setStringValue

public void setStringValue(String inKey,
                           String inValue)

Set the string value specifed by key. Sets the string value associated with the key specified by inKey to inValue. If no record is found with the key specified by inKey, a new record is created. If a record is found, its value is updated.

Parameters:

inKey - non-null; the key to look up

inValue - non-null; a String containing the value to be associated with the key.

Throws:

NullPointerException - thrown if inKey or inValue is null

IllegalArgumentException - thrown if inKey is non-null but otherwise invalid

setStringValue

public void setStringValue(String inKey,
                           String inValue,
                           boolean isDefault)

Set the string value specifed by key. Sets the string value associated with the key specified by inKey to inValue. If no record is found with the key specified by inKey, a new record is created. If a record is found, its value is updated. The isDefault flag is used when records are synchronized with the service. It lets the server know whether the setting was specified by a user, or is just the default for the program. A better way to handle this is not to store the default settings at all. If no entry is found in the database, use the default value stored in your code. If an entry is found, assume it was specified by the user.

Parameters:

inKey - non-null; the key to look up

inValue - non-null; a String containing the value to be associated with the key.

isDefault - A boolean that is true if the value was not specified by the user.

Throws:

NullPointerException - thrown if inKey or inValue is null

IllegalArgumentException - thrown if inKey is non-null but otherwise invalid

getBytes

public byte[] getBytes(String inKey)
                throws SettingsDBException

Get byte array specifed by key. Returns the byte array associated with the key specified by inKey. If no record is found with the key specified by inKey, a SettingsDBException is thrown.

Parameters:

inKey - non-null; the key to look up

Returns:

non-null; a byte array containing the value associated with the specified key.

Throws:

NullPointerException - thrown if inKey is null

IllegalArgumentException - thrown if inKey is non-null but otherwise invalid

SettingsDBException - thrown if the record is not found or is of the wrong type

getBytes

public byte[] getBytes(int i)
                throws SettingsDBException

Get byte array specifed by index. Returns the byte array associated with the record specified by index i. If no record exists at index i, a SettingsDBException is thrown.

Parameters:

i - An int specifying the index to the record to be found.

Returns:

A byte array containing the value associated with the specified record.

Throws:

NullPointerException - thrown if inKey is null

IllegalArgumentException - thrown if inKey is non-null but otherwise invalid

SettingsDBException - thrown if the record is not found or is of the wrong type

setBytes

public void setBytes(String inKey,
                     byte[] inValue)

Set the byte array specifed by key. Sets the byte array associated with the key specified by inKey to inValue. If no record is found with the key specified by inKey, a new record is created. If a record is found, its value is updated.

Parameters:

inKey - non-null; the key to look up

inValue - non-null; a byte array containing the value to be associated with the key.

Throws:

NullPointerException - thrown if inKey or inValue is null

IllegalArgumentException - thrown if inKey is non-null but otherwise invalid

setBytes

public void setBytes(String inKey,
                     byte[] inValue,
                     boolean isDefault)

Set the byte array specifed by key. Sets the byte array associated with the key specified by inKey to inValue. If no record is found with the key specified by inKey, a new record is created. If a record is found, its value is updated. The isDefault flag is used when records are synchronized with the service. It lets the server know whether the setting was specified by a user, or is just the default for the program. A better way to handle this is not to store the default settings at all. If no entry is found in the database, use the default value stored in your code. If an entry is found, assume it was specified by the user.

Parameters:

inKey - non-null; the key to look up

inValue - non-null; A byte array containing the value to be associated with the key.

isDefault - A boolean that is true if the value was not specified by the user.

Throws:

NullPointerException - thrown if inKey or inValue is null

IllegalArgumentException - thrown if inKey is non-null but otherwise invalid

setObject

public void setObject(String inKey,
                      Storable inObject)

Set the object specifed by key. Sets the object associated with the key specified by inKey to inObject. If no record is found with the key specified by inKey, a new record is created. If a record is found, its value is updated. This method is not supported for third party applications as the Storable interface is private and not extensible. It is recommended that developers use the setBytes method in combination with DataOutputStream and ByteArrayOutputStream to serialize their objects.

Parameters:

inKey - non-null; the key to look up

inObject - non-null; a Storable object containing the object to be associated with the key.

Throws:

NullPointerException - thrown if inKey or inValue is null

IllegalArgumentException - thrown if inKey is non-null but otherwise invalid

setObject

public void setObject(String inKey,
                      Storable inObject,
                      boolean isDefaultSetting)

Set the object specifed by key. Sets the object associated with the key specified by inKey to inObject. If no record is found with the key specified by inKey, a new record is created. If a record is found, its value is updated. The isDefault flag is used when records are synchronized with the service. It lets the server know whether the setting was specified by a user, or is just the default for the program. A better way to handle this is not to store the default settings at all. If no entry is found in the database, use the default value stored in your code. If an entry is found, assume it was specified by the user. This method is not supported for third party applications as the Storable interface is private and not extensible. It is recommended that developers use the setBytes method in combination with DataOutputStream and ByteArrayOutputStream to serialize their objects.

Parameters:

inKey - non-null; the key to look up

inObject - non-null; a Storable object containing the object to be associated with the key.

isDefaultSetting - A boolean that is true if the value was not specified by the user.

Throws:

NullPointerException - thrown if inKey or inValue is null

IllegalArgumentException - thrown if inKey is non-null but otherwise invalid

getObject

public void getObject(String inKey,
                      Storable ioObject)
               throws SettingsDBException

Get object specifed by key. Loads the Storable object specified by ioObject from the data associated with the key specified by inKey. If no record is found with the key specified by inKey, a SettingsDBException is thrown. This method is not supported for third party applications as the Storable interface is private and not extensible. It is recommended that developers use the getBytes method in combination with DataInputStream and ByteArrayInputStream to unserialize their objects.

Parameters:

inKey - non-null; the key to look up

ioObject - A Storable object to hold the data associated with the key.

Throws:

NullPointerException - thrown if inKey is null

IllegalArgumentException - thrown if inKey is non-null but otherwise invalid

SettingsDBException - thrown if the record is not found

remove

public String remove(String inKey)

Remove the record specifed by key. Removes the record specified by the key inKey. Returns null if the key is not found, otherwise returns the inKey string.

Parameters:

inKey - non-null; the key to look up

Returns:

A String containing the inKey string or null.

Throws:

NullPointerException - thrown if inKey is null

IllegalArgumentException - thrown if inKey is non-null but otherwise invalid

resolveAllRecords

protected void resolveAllRecords()

Resolves each record with every other record in the settings database. Resolves each record with every other record in the settings database. This is a more paranoid way of resolving records. It validates each record against every other record, even if all of them are auto-sync'd from the service. So, if the service screwed up, and say, created duplicate records, this method will go clean up the settings database and remove the duplicates.

resolveAutoSyncConflicts

protected void resolveAutoSyncConflicts()

Resolves potential conflicts caused by auto-syncing the data from Danger service. If a settings database is marked for auto-sync, then this method gets called after an auto-sync from Danger service takes place (this happens after a device hard reset). If there are conflicts in the settings database, this method attempts to resolve them. Conflicts may arise because the user or application added to the settings database before the auto-sync takes place. Currently this method calls ResolveAllRecords() to do the actual conflict resolution.

setAutoSyncNotifyee

public void setAutoSyncNotifyee(Listener inNotifyee)

Set the Listener for AutoSync events. Sets the listener object that will receive AutoSync related events. If no listener has been set AutoSync events will be sent to the current application.

Parameters:

inNotifyee - The listener to be notified of the autosync events.

registerAutoSyncBundleListener

public void registerAutoSyncBundleListener(Bundle bundle)

register autosync listener with datastore Registers with datastore the autosync listener and the datastore's owner bundle.

Parameters:

bundle - The owner bundle of the datastore