danger.app
Class DataStore

java.lang.Object
  danger.app.DataStore

All Implemented Interfaces:

Comparable

public final class DataStore
extends Object
implements Comparable

A container for records of data, each identified by a unique integer value.

Applications can use one or more DataStores to store data that must persist across device reboots.

DataStores can either be local to the device, or 'synced' with the backend service.

A Datastore can be either 'private' or 'shared'.

DataStore modification
DataStores are modified by adding, updating and removing records. When a modification is made, the DataStore's Last Modified time is updated.

Field Summary

static int	AUTO_SYNC_WAIT_FOR_CONFIRM Deprecated. For internal use only.
static boolean	DEBUG_AUTO_SYNC Deprecated. For internal use only.
static boolean	DEBUG_AUTO_SYNC_UID Deprecated. For internal use only.
static String	DS_SCHEDULED_FOR_ACTIVATION Deprecated. For internal use only.
static int	RECORD_FLAG_MASK Deprecated. For internal use only.
static int	RECORD_MODIFIED Deprecated. For internal use only.

Method Summary

int	addRecord(byte[] data) Add a new record with flags=0, return its number
int	addRecord(byte[] data, int flags) Deprecated. For internal use only.
int	addRecord(byte[] data, int flags, int uid) Deprecated. For internal use only.
static void	allowAutoSyncToService(boolean flag) Deprecated. For internal use only.
boolean	autoSync() Returns information about whether this is an autosynced DataStore (i.e. a DataStore that will be synced with the service at regular intervals.)
void	autoSyncFromServiceDone() Deprecated. For internal use only.
static boolean	autoSyncToService() Deprecated. For internal use only.
int	binarySearch(Comparator inComparator, byte[] inKey)
int	binarySearch(int inUID)
static void	broadcastAutoSyncDone() Deprecated. For internal use only.
int	compareTo(Object o)
static DataStore	createDataStore(String name)
static DataStore	createDataStore(String name, boolean autoSync)
static DataStore	createSharedDataStore(String name) Create a new shared DataStore by name.
static DataStore	createSharedDataStore(String name, boolean autoSync)
static boolean	dataStoresPendingActivation() Deprecated. For internal use only.
static void	deleteDataStore(DataStore inDS)
static void	deleteLocalDataStore(DataStore inDS) Deprecated. For internal use only.
static void	deregisterListenerForAutoSyncDone(Listener inListener)
static void	discardAllOnReboot() Deprecated. For internal use only.
boolean	discardOnReboot()
void	discardOnReboot(boolean flag)
void	doneResolvingConflict()
static void	dumpList() Prints out the data stores for all applications to the system log.
static void	dumpList(Application app) Prints out the data stores for the given application to the system log.
static DataStore	findDataStore(String name) Locate a DataStore by name.
static DataStore	findSharedDataStore(String name) Locate a shared DataStore by name.
static void	flattenStores() Deprecated. For internal use only.
static String[]	getAllFullNames() Deprecated. For internal use only.
int	getAutoSyncNextUID() Deprecated. For internal use only.
int	getByteSize() Returns the total number of bytes (including any additional bytes used by the internal structure of the DataStore) this DataStore and its records are occupying.
int	getBytesUsed() Returns the total number of bytes actually representing record data in this DataStore.
String	getDBName()
String	getFullName() Returns the full name of the database (which will be slightly different than the name an app uses to find the database)
int	getLastModified() Returns the time (in "Danger seconds", the number of seconds since January 1, 2000 GMT) at which the DataStore was last modified.
long	getLastModifiedMillis() Returns the time (in milliseconds since January 1, 1970 GMT) at which the DataStore was last modified.
int	getLastSynced() Returns the time (in Danger seconds) when the DataStore was last synced.
long	getLastSyncedMillis() Returns the time (in milliseconds since January 1, 1970 GMT) when the DataStore was last synced.
int	getRecordCount() Returns the number of records in the DataStore.
byte[]	getRecordData(int n) Returns the byte array of the record with index n.
byte[]	getRecordDataByUID(int uid) Returns the byte array of the record with the specified uid.
int	getRecordFlags(int n) Deprecated. For internal use only.
int	getRecordIndexByUID(int uid) Returns the index of the record with a given uid.
byte[][]	getRecords() obtain an array of byte arrays for all records
int	getRecordUID(int n) Returns the UID of the record with index n.
int	getVersion() Returns the application defined version number of this DataStore.
static Object	initialize() Deprecated. For internal use only.
int	insertRecord(byte[] data, int index) Insert a new record
int	insertRecord(byte[] data, int index, int flags) Deprecated. For internal use only.
int	insertRecordSorted(Comparator inComparator, byte[] inItem)
int	insertRecordSorted(int inUID, byte[] inItem)
boolean	isRecordDirty(int n) Checks whether the record with index n has been modified.
static boolean	journalReconcile(Object inKey, String inName) Deprecated. For internal use only.
static void	processBackingStoreResponse(BackingStoreTransaction bt) Deprecated. For internal use only.
static void	recoverDataStores() Deprecated. For internal use only.
static void	registerListenerForAutoSyncDone(Listener inListener)
void	removeAllRecords() Remove all records from the DataStore.
void	removeRecord(int n) Removes the record with zero-based index n from the DataStore.
void	removeRecordByUID(int uid) Finds the index of the record with the specified UID and calls removeRecord(int) for this record.
void	removeRecordWithoutAutoSync(int n) Deprecated. For internal use only.
void	setAutoSyncNotifyee(Listener inNotifyee) Specifies the listener that should be sent an Event.EVENT_DATASTORE_RESTORED after this DataStore has been successfuly restored from the service.
void	setAutoSyncNotifyee(Listener inNotifyee, Bundle bundle) Deprecated. For internal use only.
void	setRecordData(int n, byte[] data) Replaces the data of the record with index n with the data of the provided byte array, sets the record's dirty flag, and updates the DataStore's last modified time.
void	setRecordData(int n, byte[] data, boolean makeDirty) Replaces the data of the record with index n with the data of the provided byte array.
void	setRecordDataByUID(int uid, byte[] data) Replaces the data of the record with id uid with the data of the provided byte array, sets the record's dirty flag, and updates the DataStore's last modified time.
void	setRecordDataByUID(int uid, byte[] data, boolean makeDirty) Deprecated. For internal use only.
void	setRecordDirty(int n, boolean flag) Sets or clears the Record Dirty flag of the record with index n.
void	setRecordFlags(int n, int flags) Deprecated. For internal use only.
void	setRecordFlagsByUID(int uid, int flags) Deprecated. For internal use only.
void	setRecordUID(int n, int uid) Deprecated. For internal use only.
void	setVersion(int inVersion) Allows applications to specify a version number to this DataStore.
void	sort(Comparator comparator)
void	sortByUID()
void	swapRecords(int this_rec, int that_rec) Exchange the data and flags of this_rec with that_rec.
void	updateLastModified() Deprecated. For internal use only.
void	updateLastSynced() Deprecated. For internal use only.

Methods inherited from class java.lang.Object

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

Field Detail

DS_SCHEDULED_FOR_ACTIVATION

public static final String DS_SCHEDULED_FOR_ACTIVATION

Deprecated. For internal use only.

See Also:

Constant Field Values

RECORD_MODIFIED

public static final int RECORD_MODIFIED

Deprecated. For internal use only.

See Also:

Constant Field Values

AUTO_SYNC_WAIT_FOR_CONFIRM

public static final int AUTO_SYNC_WAIT_FOR_CONFIRM

Deprecated. For internal use only.

See Also:

Constant Field Values

RECORD_FLAG_MASK

public static final int RECORD_FLAG_MASK

Deprecated. For internal use only.

See Also:

Constant Field Values

DEBUG_AUTO_SYNC

public static final boolean DEBUG_AUTO_SYNC

Deprecated. For internal use only.

See Also:

Constant Field Values

DEBUG_AUTO_SYNC_UID

public static final boolean DEBUG_AUTO_SYNC_UID

Deprecated. For internal use only.

See Also:

Constant Field Values

Method Detail

initialize

public static Object initialize()

Deprecated. For internal use only.

dataStoresPendingActivation

public static boolean dataStoresPendingActivation()

Deprecated. For internal use only.

flattenStores

public static void flattenStores()
                          throws IOException

Deprecated. For internal use only.

Throws:

IOException

dumpList

public static void dumpList()

Prints out the data stores for all applications to the system log.

dumpList

public static void dumpList(Application app)

Prints out the data stores for the given application to the system log.

Parameters:

app - the application whose data stores should be printed out, or null for all applications

Since:

4.0

compareTo

public int compareTo(Object o)

Specified by:

compareTo in interface Comparable

discardAllOnReboot

public static void discardAllOnReboot()

Deprecated. For internal use only.

createDataStore

public static DataStore createDataStore(String name)

createDataStore

public static DataStore createDataStore(String name,
                                        boolean autoSync)

createSharedDataStore

public static DataStore createSharedDataStore(String name)

Create a new shared DataStore by name. If DataStore already exists, return the existing one. (Shared datastores are not application-local -- any app can access a shared datastore. The PhotoGallery is an example of a shared datastore.)

createSharedDataStore

public static DataStore createSharedDataStore(String name,
                                              boolean autoSync)

deleteDataStore

public static void deleteDataStore(DataStore inDS)

deleteLocalDataStore

public static void deleteLocalDataStore(DataStore inDS)

Deprecated. For internal use only.

recoverDataStores

public static void recoverDataStores()

Deprecated. For internal use only.

Only used during system startup.

getAllFullNames

public static String[] getAllFullNames()

Deprecated. For internal use only.

findDataStore

public static DataStore findDataStore(String name)

Locate a DataStore by name. If not found, return null. (DataStores namespaces are application-local -- you cannot open another apps DataStores)

findSharedDataStore

public static DataStore findSharedDataStore(String name)

Locate a shared DataStore by name. If not found, return null (Shared datastores are not application-local -- any app can access them. The PhotoGallery is a shared datastore.)

setVersion

public void setVersion(int inVersion)

Allows applications to specify a version number to this DataStore.

Parameters:

inVersion - the application-defined version number of this DataStore.

getVersion

public int getVersion()

Returns the application defined version number of this DataStore.

autoSyncToService

public static boolean autoSyncToService()

Deprecated. For internal use only.

processBackingStoreResponse

public static void processBackingStoreResponse(BackingStoreTransaction bt)

Deprecated. For internal use only.

getRecordCount

public int getRecordCount()

Returns the number of records in the DataStore.

getLastModifiedMillis

public long getLastModifiedMillis()

Returns the time (in milliseconds since January 1, 1970 GMT) at which the DataStore was last modified. Adding or Removing a record, or Setting record data with the provided methods of DataStore will cause this timestamp on the DataStore to update. Modifying the contents of a record's existing byte array will not.

getLastModified

public int getLastModified()

Returns the time (in "Danger seconds", the number of seconds since January 1, 2000 GMT) at which the DataStore was last modified. Adding or Removing a record, or Setting record data with the provided methods of DataStore will cause this timestamp on the DataStore to update. Modifying the contents of a record's existing byte array will not.

getLastSyncedMillis

public long getLastSyncedMillis()

Returns the time (in milliseconds since January 1, 1970 GMT) when the DataStore was last synced.

getLastSynced

public int getLastSynced()

Returns the time (in Danger seconds) when the DataStore was last synced.

getFullName

public String getFullName()

Returns the full name of the database (which will be slightly different than the name an app uses to find the database)

getDBName

public String getDBName()

updateLastModified

public void updateLastModified()

Deprecated. For internal use only.

updateLastSynced

public void updateLastSynced()

Deprecated. For internal use only.

discardOnReboot

public void discardOnReboot(boolean flag)

discardOnReboot

public boolean discardOnReboot()

autoSync

public boolean autoSync()

Returns information about whether this is an autosynced DataStore (i.e. a DataStore that will be synced with the service at regular intervals.)

Returns:

true if this is an autosynced DataStore, false if it is not.

getAutoSyncNextUID

public int getAutoSyncNextUID()

Deprecated. For internal use only.

addRecord

public int addRecord(byte[] data)

Add a new record with flags=0, return its number

addRecord

public int addRecord(byte[] data,
                     int flags)

Deprecated. For internal use only.

Adds a new record to this DataStore. The record's flags will be set as specified.

Parameters:

data - The byte array that contains the new record's data.

flags - The flags to associate with the new record.

Returns:

The index at which the new record was added to the DataStore.

addRecord

public int addRecord(byte[] data,
                     int flags,
                     int uid)

Deprecated. For internal use only.

Add a new record, return its number.

insertRecord

public int insertRecord(byte[] data,
                        int index)

Insert a new record

insertRecord

public int insertRecord(byte[] data,
                        int index,
                        int flags)

Deprecated. For internal use only.

Insert a new record

removeRecord

public void removeRecord(int n)

Removes the record with zero-based index n from the DataStore. If n is an invalid index, returns without any effect. If this is an autosynced DataStore, the record is also scheduled to be removed from the service. After the record has been removed, any records with a higher index will have their index updated.

removeRecordWithoutAutoSync

public void removeRecordWithoutAutoSync(int n)

Deprecated. For internal use only.

removeRecordByUID

public void removeRecordByUID(int uid)

Finds the index of the record with the specified UID and calls removeRecord(int) for this record. Does nothing if no record with the specified UID exists.

Parameters:

uid - the uid of the record to be removed.

removeAllRecords

public void removeAllRecords()

Remove all records from the DataStore. Be careful using this API. If the data store is an auto-sync DB, RemoveAllRecords() will remove all the records of this database on the service.

getRecords

public byte[][] getRecords()

obtain an array of byte arrays for all records

getRecordData

public byte[] getRecordData(int n)

Returns the byte array of the record with index n.

Parameters:

n - The index of the record whose byte array reference to return.

Returns:

The byte array of the record with index n. null if n specifies an invalid index.

getRecordIndexByUID

public int getRecordIndexByUID(int uid)

Returns the index of the record with a given uid.

Parameters:

uid - The uid to search for.

Returns:

The index of the record with that uid, or -1 if there is no record with that uid.

getRecordDataByUID

public byte[] getRecordDataByUID(int uid)

Returns the byte array of the record with the specified uid.

Parameters:

uid - The uid to search for.

Returns:

The byte array, or null if there is no record with that uid.

getRecordFlags

public int getRecordFlags(int n)

Deprecated. For internal use only.

Returns the flags of the record with index n.

Parameters:

n - The index of the record for which to return its flags.

Returns:

The flags of the record with index x, or 0 there is no record with index n.

isRecordDirty

public boolean isRecordDirty(int n)

Checks whether the record with index n has been modified.

Parameters:

n - The index of the record to check.

Returns:

true is the record with index n has been modified, false if is has not been modified. Also, false is returned if there is no record with index n.

getRecordUID

public int getRecordUID(int n)

Returns the UID of the record with index n.

Parameters:

n - The index of the record for which to return its UID.

Returns:

the UID of the record with the specified index. Returns 0 if n specifies an invalid index.

setRecordData

public void setRecordData(int n,
                          byte[] data)

Replaces the data of the record with index n with the data of the provided byte array, sets the record's dirty flag, and updates the DataStore's last modified time. Does nothing if n specifies an invalid index.

Parameters:

n - The index of the record whose record data to replace.

data - The record data that replaces the old record data.

setRecordData

public void setRecordData(int n,
                          byte[] data,
                          boolean makeDirty)

Replaces the data of the record with index n with the data of the provided byte array. Does nothing if n specifies an invalid index. This method is here for backwards compatibility with older applications, please use setRecordData(int n, byte[] data) instead.

Parameters:

n - The index of the record whose record data to replace.

data - The record data that replaces the old record data.

makeDirty - true if the record's dirty flag, and the dataStore's lastModified time should be set, false if not.

setRecordDataByUID

public void setRecordDataByUID(int uid,
                               byte[] data)

Replaces the data of the record with id uid with the data of the provided byte array, sets the record's dirty flag, and updates the DataStore's last modified time. Does nothing if a record with id uid does not exist.

Parameters:

uid - The id of the record whose record data to replace.

data - The record data that replaces the old record data.

setRecordDataByUID

public void setRecordDataByUID(int uid,
                               byte[] data,
                               boolean makeDirty)

Deprecated. For internal use only.

setRecordFlags

public void setRecordFlags(int n,
                           int flags)

Deprecated. For internal use only.

Sets the non-reserved record flags of the record specified by the index, to the flags passed to this method, but leaves the reserved flags (those masked by RECORD_FLAG_MASK) of the specified record untouched. Historically, non-DataStore code has been allowed to use the record's non-reserved flags for its own purpose. But it is recommended that non-DataStore code does NOT use these non-reserved flags in any way.

Parameters:

n - The index of the record whose non-reserved flags to set.

flags - The flags to set the record's non-reserved flags to.

setRecordFlagsByUID

public void setRecordFlagsByUID(int uid,
                                int flags)

Deprecated. For internal use only.

Sets the non-reserved record flags of the record specified by the uid, to the flags passed to this method, but leaves the reserved flags (those masked by RECORD_FLAG_MASK) of the specified record untouched. Historically, non-DataStore code has been allowed to use the record's non-reserved flags for its own purpose. But it is recommended that non-DataStore code does NOT use these non-reserved flags in any way.

Parameters:

uid - The uid of the record whose non-reserved flags to set.

flags - The flags to set the record's non-reserved flags to.

setRecordDirty

public void setRecordDirty(int n,
                           boolean flag)

Sets or clears the Record Dirty flag of the record with index n.

Parameters:

n - The index of the record for which to set or clear the flag. This method does nothing if n specifies an invalid index.

flag - true if the flag should be set, false if the flag should be cleared.

setRecordUID

public void setRecordUID(int n,
                         int uid)

Deprecated. For internal use only.

sort

public void sort(Comparator comparator)

sortByUID

public void sortByUID()

insertRecordSorted

public int insertRecordSorted(Comparator inComparator,
                              byte[] inItem)

insertRecordSorted

public int insertRecordSorted(int inUID,
                              byte[] inItem)

binarySearch

public int binarySearch(int inUID)

binarySearch

public int binarySearch(Comparator inComparator,
                        byte[] inKey)

swapRecords

public void swapRecords(int this_rec,
                        int that_rec)

Exchange the data and flags of this_rec with that_rec. This allows records to be reordered.

autoSyncFromServiceDone

public void autoSyncFromServiceDone()

Deprecated. For internal use only.

doneResolvingConflict

public void doneResolvingConflict()

setAutoSyncNotifyee

public void setAutoSyncNotifyee(Listener inNotifyee)

Specifies the listener that should be sent an Event.EVENT_DATASTORE_RESTORED after this DataStore has been successfuly restored from the service.

It is extremely important that if the application registers a listener via setAutoSyncNotifyee(danger.app.Listener), that listener MUST call doneResolvingConflict(). This is because doneResolvingConflict() has the side effect of re-enabling that DataStore for autosyncing with the service.

setAutoSyncNotifyee

public void setAutoSyncNotifyee(Listener inNotifyee,
                                Bundle bundle)

Deprecated. For internal use only.

allowAutoSyncToService

public static void allowAutoSyncToService(boolean flag)

Deprecated. For internal use only.

getByteSize

public int getByteSize()

Returns the total number of bytes (including any additional bytes used by the internal structure of the DataStore) this DataStore and its records are occupying.

getBytesUsed

public int getBytesUsed()

Returns the total number of bytes actually representing record data in this DataStore. This number is smaller than that returned by getByteSize() because the overhead imposed by the DataStore's internal representation, is not included in this number.

registerListenerForAutoSyncDone

public static void registerListenerForAutoSyncDone(Listener inListener)

deregisterListenerForAutoSyncDone

public static void deregisterListenerForAutoSyncDone(Listener inListener)

broadcastAutoSyncDone

public static void broadcastAutoSyncDone()

Deprecated. For internal use only.

journalReconcile

public static boolean journalReconcile(Object inKey,
                                       String inName)

Deprecated. For internal use only.