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. The setting key is a string, and cannot be longer than 256 characters. The setting value can be of integer, string, byte arrays. The keys of a SettingsDB need to be unique. Each key and value pair is stored in the record field in the DataStore. The SettingsDB has a corresponding DataStore on the device. Since DataStore can be autosync'd with the service, SettingsDB can be autosync'd as well. Note that SettingsDB namespaces are local to an application, and one application cannot open another applications SettingsDB.

Field Summary

protected static boolean	DEBUG_CONFLICT_RESOLVE
protected static boolean	DEBUG_CONFLICT_RESOLVE_VERBOSE
protected static boolean	DEBUG_SORT
protected static boolean	IS_DEBUG
static int	kDataType_Bytes
static int	kDataType_Integer
static int	kDataType_String
protected static int	kDefaultSetting
protected Listener	mAutoSyncNotifyee
protected DataStore	mDataStore

Constructor Summary

SettingsDB(java.lang.String dbName)
Create or get a SettingsDB.

SettingsDB(java.lang.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(java.lang.String inKey) Find and return the index for a record in the database.
protected int	find2(java.lang.String inKey) Find and return the index for a record in the database.
static boolean	findDB(java.lang.String dbName) Find a settings database.
static boolean	findDB(java.lang.String dbName, boolean absolutePath) Find a settings database.
byte[]	getBytes(int i) Get byte array specifed by index.
byte[]	getBytes(java.lang.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(java.lang.String inKey) Get integer value specifed by key.
java.lang.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(java.lang.String inKey, danger.io.Storable ioObject) Get object specifed by key.
java.lang.String	getStringValue(int i) Get string value specifed by index.
java.lang.String	getStringValue(java.lang.String inKey) Get string value specifed by key.
boolean	receiveEvent(Event e) Receive a SettingsDB-related event.
java.lang.String	remove(java.lang.String inKey) Remove the record specifed by key.
boolean	renameKey(int i, java.lang.String newKey) Rename a specific key in a settings database.
boolean	renameKey(java.lang.String oldKey, java.lang.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(java.lang.String inKey, byte[] inValue) Set the byte array specifed by key.
void	setBytes(java.lang.String inKey, byte[] inValue, boolean isDefault) Set the byte array specifed by key.
void	setIntValue(java.lang.String inKey, int inValue) Set the integer value specifed by key.
void	setIntValue(java.lang.String inKey, int inValue, boolean isDefault) Set the integer value specifed by key.
void	setObject(java.lang.String inKey, danger.io.Storable inObject) Set the object specifed by key.
void	setObject(java.lang.String inKey, danger.io.Storable inObject, boolean isDefaultSetting) Set the object specifed by key.
void	setStringValue(java.lang.String inKey, java.lang.String inValue) Set the string value specifed by key.
void	setStringValue(java.lang.String inKey, java.lang.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, receiveEventInternal, sendEvent, sendEvent

Methods inherited from class java.lang.Object

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

Field Detail

mDataStore

protected DataStore mDataStore

mAutoSyncNotifyee

protected Listener mAutoSyncNotifyee

kDataType_Integer

public static final int kDataType_Integer

kDataType_String

public static final int kDataType_String

kDataType_Bytes

public static final int kDataType_Bytes

kDefaultSetting

protected static final int kDefaultSetting

IS_DEBUG

protected static final boolean IS_DEBUG

DEBUG_CONFLICT_RESOLVE

protected static final boolean DEBUG_CONFLICT_RESOLVE

DEBUG_CONFLICT_RESOLVE_VERBOSE

protected static final boolean DEBUG_CONFLICT_RESOLVE_VERBOSE

DEBUG_SORT

protected static final boolean DEBUG_SORT

Constructor Detail

SettingsDB

public SettingsDB(java.lang.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(java.lang.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(java.lang.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(java.lang.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 java.lang.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(java.lang.String oldKey,
                         java.lang.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,
                         java.lang.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(java.lang.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(java.lang.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(java.lang.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 - A String specifying the key to be found. String keys cannot be longer than 128, and is case sensitive.

Returns:

An int containing the value associated with the specified key.

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.

setIntValue

public void setIntValue(java.lang.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 - A String specifying the key to be found. String keys cannot be longer than 128, and is case sensitive.

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

setIntValue

public void setIntValue(java.lang.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 - A String specifying the key to be found. String keys cannot be longer than 128, and is case sensitive.

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.

getStringValue

public java.lang.String getStringValue(java.lang.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, a SettingsDBException is thrown.

Parameters:

inKey - A String specifying the key to be found. String keys cannot be longer than 128, and is case sensitive.

Returns:

A String containing the value associated with the specified key.

getStringValue

public java.lang.String getStringValue(int i)

Get string value specifed by index. Returns the string 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:

A String containing the value associated with the specified record.

setStringValue

public void setStringValue(java.lang.String inKey,
                           java.lang.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 - A String specifying the key to be found. String keys cannot be longer than 128, and is case sensitive.

inValue - A String containing the value to be associated with the key.

setStringValue

public void setStringValue(java.lang.String inKey,
                           java.lang.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 - A String specifying the key to be found. String keys cannot be longer than 128, and is case sensitive.

inValue - 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.

getBytes

public byte[] getBytes(java.lang.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 - A String specifying the key to be found. String keys cannot be longer than 128, and is case sensitive.

Returns:

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

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.

setBytes

public void setBytes(java.lang.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 - A String specifying the key to be found. String keys cannot be longer than 128, and is case sensitive.

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

setBytes

public void setBytes(java.lang.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 - A String specifying the key to be found. String keys cannot be longer than 128, and is case sensitive.

inValue - 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.

setObject

public void setObject(java.lang.String inKey,
                      danger.io.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.

Parameters:

inKey - A String specifying the key to be found. String keys cannot be longer than 128, and is case sensitive.

inObject - A Storable object containing the object to be associated with the key.

setObject

public void setObject(java.lang.String inKey,
                      danger.io.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.

Parameters:

inKey - A String specifying the key to be found. String keys cannot be longer than 128, and is case sensitive.

inObject - 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.

getObject

public void getObject(java.lang.String inKey,
                      danger.io.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.

Parameters:

inKey - A String specifying the key to be found. String keys cannot be longer than 128, and is case sensitive.

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

remove

public java.lang.String remove(java.lang.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 - A String specifying the key to be found.

Returns:

A String containing the inKey string or null.

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.