com.salesforce.androidsdk.smartstore.store

Class SmartStore

java.lang.Object

com.salesforce.androidsdk.smartstore.store.SmartStore

public class SmartStore
extends java.lang.Object

Smart store Provides a secure means for SalesforceMobileSDK Container-based applications to store objects in a persistent and searchable manner. Similar in some ways to CouchDB, SmartStore stores documents as JSON values. SmartStore is inspired by the Apple Newton OS Soup/Store model. The main challenge here is how to effectively store documents with dynamic fields, and still allow indexing and searching.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SmartStore.FtsExtension Enum for fts extensions
static class	SmartStore.SmartStoreException Exception thrown by smart store
static class	SmartStore.Type Enum for column type
static class	SmartStore.TypeGroup Enum for type groups

Field Summary

Fields

Modifier and Type	Field and Description
protected static java.lang.String	COLUMN_NAME_COL
static java.lang.String	COLUMN_TYPE_COL
protected static java.lang.String	CREATED_COL
protected SQLiteOpenHelper	dbOpenHelper
protected static java.lang.String	DETAILS_COL
static java.lang.String	FTS_SUFFIX
protected SmartStore.FtsExtension	ftsExtension
protected static java.lang.String	ID_COL
protected static java.lang.String	ID_PREDICATE
protected static java.lang.String	LAST_MODIFIED_COL
protected static java.lang.String	LONG_OPERATIONS_STATUS_TABLE
static java.lang.String	PATH_COL
protected static java.lang.String	ROWID_COL
protected static java.lang.String	ROWID_PREDICATE
static java.lang.String	SOUP_ATTRS_TABLE
protected static java.lang.String	SOUP_COL
static java.lang.String	SOUP_CREATED_DATE
static java.lang.String	SOUP_ENTRY_ID
static java.lang.String	SOUP_INDEX_MAP_TABLE
static java.lang.String	SOUP_LAST_MODIFIED_DATE
static java.lang.String	SOUP_NAME_COL
protected static java.lang.String	SOUP_NAME_PREDICATE
protected static java.lang.String	STATUS_COL
protected static java.lang.String	TYPE_COL

Constructor Summary

Constructors

Constructor and Description
SmartStore(SQLiteOpenHelper dbOpenHelper) Relies on SQLiteOpenHelper for database handling.

Method Summary

Modifier and Type	Method and Description
void	alterSoup(java.lang.String soupName, IndexSpec[] indexSpecs, boolean reIndexData) Alter soup using only soup name without extra soup features.
void	beginTransaction() Start transaction NB: to avoid deadlock, caller should have synchronized(store.getDatabase()) around the whole transaction
static void	changeKey(SQLiteDatabase db, java.lang.String oldKey, java.lang.String newKey) Changes the encryption key on the smartstore.
void	clearSoup(java.lang.String soupName) Clear all rows from a soup
java.lang.String	convertSmartSql(java.lang.String smartSql)
int	countQuery(QuerySpec querySpec)
JSONObject	create(java.lang.String soupName, JSONObject soupElt) Create (and commits) Note: Passed soupElt is modified (last modified date and soup entry id fields)
JSONObject	create(java.lang.String soupName, JSONObject soupElt, boolean handleTx) Create Note: Passed soupElt is modified (last modified date and soup entry id fields)
static void	createLongOperationsStatusTable(SQLiteDatabase db) Create long_operations_status table
static void	createMetaTables(SQLiteDatabase db) Create soup index map table to keep track of soups' index specs Create soup name map table to keep track of soup name to table name mappings Called when the database is first created
void	delete(java.lang.String soupName, java.lang.Long... soupEntryIds) Delete soup elements given by their ids (and commits)
void	delete(java.lang.String soupName, java.lang.Long[] soupEntryIds, boolean handleTx) Delete soup elements given by their ids
void	deleteByQuery(java.lang.String soupName, QuerySpec querySpec) Delete soup elements selected by querySpec (and commits)
void	deleteByQuery(java.lang.String soupName, QuerySpec querySpec, boolean handleTx) Delete soup elements selected by querySpec
void	dropAllSoups() Destroy all the soups in the smartstore
void	dropSoup(java.lang.String soupName) Destroy a soup Drop table for soupName Cleanup entries in soup index map table
void	endTransaction() End transaction (commit or rollback)
java.util.List<java.lang.String>	getAllSoupNames()
java.util.List<java.lang.String>	getCompileOptions() Get SQLCipher compile options
SQLiteDatabase	getDatabase() Return db
int	getDatabaseSize() Get database size
SmartStore.FtsExtension	getFtsExtension()
JSONObject	getLastExplainQueryPlan()
LongOperation[]	getLongOperations()
java.util.List<java.lang.String>	getRuntimeSettings() Get SQLCipher runtime settings
IndexSpec[]	getSoupIndexSpecs(java.lang.String soupName) Return indexSpecs of soup
static java.lang.String	getSoupTableName(long soupId)
java.lang.String	getSQLCipherVersion() Get SQLCipher version
boolean	hasIndexForPath(java.lang.String soupName, java.lang.String path) Return true if the given path is indexed on the given soup
boolean	hasSoup(java.lang.String soupName) Check if soup exists
long	lookupSoupEntryId(java.lang.String soupName, java.lang.String fieldPath, java.lang.String fieldValue) Look for a soup element where fieldPath's value is fieldValue Return its soupEntryId Return -1 if not found Throw an exception if fieldName is not indexed Throw an exception if more than one soup element are found
static java.lang.Object	project(JSONObject soup, java.lang.String path)
static java.lang.Object	projectReturningNULLObject(JSONObject soup, java.lang.String path) Same as project but returns JSONObject.NULL if node found but without value and null if node not found
JSONArray	query(QuerySpec querySpec, int pageIndex) Run a query given by its query spec Returns results from selected page
void	queryAsString(java.lang.StringBuilder resultBuilder, QuerySpec querySpec, int pageIndex) Run a query given by its query Spec Returns results from selected page without deserializing any JSON
JSONArray	queryWithArgs(QuerySpec querySpec, int pageIndex, java.lang.String... whereArgs) Run a query given by its query spec with optional "where args" (i.e.
void	registerSoup(java.lang.String soupName, IndexSpec[] indexSpecs) Register a soup.
protected void	registerSoupUsingTableName(java.lang.String soupName, IndexSpec[] indexSpecs, java.lang.String soupTableName) Helper method for registerSoup
void	reIndexSoup(java.lang.String soupName, java.lang.String[] indexPaths, boolean handleTx) Re-index all soup elements for passed indexPaths NB: only indexPath that have IndexSpec on them will be indexed
void	resumeLongOperations() Finish long operations that were interrupted
JSONArray	retrieve(java.lang.String soupName, java.lang.Long... soupEntryIds) Retrieve
void	setCaptureExplainQueryPlan(boolean captureExplainQueryPlan) If turned on, explain query plan is run before executing a query and stored in lastExplainQueryPlan and also get logged
void	setFtsExtension(SmartStore.FtsExtension ftsExtension) Sets the ftsX to be used when creating the virtual table to support full_text queries NB: only used in tests
void	setTransactionSuccessful() Mark transaction as successful (next call to endTransaction will be a commit)
JSONObject	update(java.lang.String soupName, JSONObject soupElt, long soupEntryId) Update (and commits) Note: Passed soupElt is modified (last modified date and soup entry id fields)
JSONObject	update(java.lang.String soupName, JSONObject soupElt, long soupEntryId, boolean handleTx) Update Note: Passed soupElt is modified (last modified date and soup entry id fields)
static void	updateTableNameAndAddColumns(SQLiteDatabase db, java.lang.String oldName, java.lang.String newName, java.lang.String[] columns) Updates the given table with a new name and adds columns if any.
JSONObject	upsert(java.lang.String soupName, JSONObject soupElt) Upsert (and commits) expecting _soupEntryId in soupElt for updates
JSONObject	upsert(java.lang.String soupName, JSONObject soupElt, java.lang.String externalIdPath) Upsert (and commits)
JSONObject	upsert(java.lang.String soupName, JSONObject soupElt, java.lang.String externalIdPath, boolean handleTx) Upsert

Methods inherited from class java.lang.Object

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

Field Detail

SOUP_ATTRS_TABLE

public static final java.lang.String SOUP_ATTRS_TABLE

See Also:

Constant Field Values

FTS_SUFFIX

public static final java.lang.String FTS_SUFFIX

See Also:

Constant Field Values

SOUP_INDEX_MAP_TABLE

public static final java.lang.String SOUP_INDEX_MAP_TABLE

See Also:

Constant Field Values

LONG_OPERATIONS_STATUS_TABLE

protected static final java.lang.String LONG_OPERATIONS_STATUS_TABLE

See Also:

Constant Field Values

SOUP_NAME_COL

public static final java.lang.String SOUP_NAME_COL

See Also:

Constant Field Values

PATH_COL

public static final java.lang.String PATH_COL

See Also:

Constant Field Values

COLUMN_NAME_COL

protected static final java.lang.String COLUMN_NAME_COL

See Also:

Constant Field Values

COLUMN_TYPE_COL

public static final java.lang.String COLUMN_TYPE_COL

See Also:

Constant Field Values

ID_COL

protected static final java.lang.String ID_COL

See Also:

Constant Field Values

CREATED_COL

protected static final java.lang.String CREATED_COL

See Also:

Constant Field Values

LAST_MODIFIED_COL

protected static final java.lang.String LAST_MODIFIED_COL

See Also:

Constant Field Values

SOUP_COL

protected static final java.lang.String SOUP_COL

See Also:

Constant Field Values

ROWID_COL

protected static final java.lang.String ROWID_COL

See Also:

Constant Field Values

TYPE_COL

protected static final java.lang.String TYPE_COL

See Also:

Constant Field Values

DETAILS_COL

protected static final java.lang.String DETAILS_COL

See Also:

Constant Field Values

STATUS_COL

protected static final java.lang.String STATUS_COL

See Also:

Constant Field Values

SOUP_ENTRY_ID

public static final java.lang.String SOUP_ENTRY_ID

See Also:

Constant Field Values

SOUP_LAST_MODIFIED_DATE

public static final java.lang.String SOUP_LAST_MODIFIED_DATE

See Also:

Constant Field Values

SOUP_CREATED_DATE

public static final java.lang.String SOUP_CREATED_DATE

See Also:

Constant Field Values

SOUP_NAME_PREDICATE

protected static final java.lang.String SOUP_NAME_PREDICATE

See Also:

Constant Field Values

ID_PREDICATE

protected static final java.lang.String ID_PREDICATE

See Also:

Constant Field Values

ROWID_PREDICATE

protected static final java.lang.String ROWID_PREDICATE

See Also:

Constant Field Values

dbOpenHelper

protected SQLiteOpenHelper dbOpenHelper

ftsExtension

protected SmartStore.FtsExtension ftsExtension

Constructor Detail

SmartStore

public SmartStore(SQLiteOpenHelper dbOpenHelper)

Relies on SQLiteOpenHelper for database handling.

Parameters:

dbOpenHelper - DB open helper.

Method Detail

changeKey

public static void changeKey(SQLiteDatabase db,
                             java.lang.String oldKey,
                             java.lang.String newKey)

Changes the encryption key on the smartstore.

Parameters:

db - Database object.

oldKey - Old encryption key.

newKey - New encryption key.

createMetaTables

public static void createMetaTables(SQLiteDatabase db)

Create soup index map table to keep track of soups' index specs Create soup name map table to keep track of soup name to table name mappings Called when the database is first created

Parameters:

db -

createLongOperationsStatusTable

public static void createLongOperationsStatusTable(SQLiteDatabase db)

Create long_operations_status table

Parameters:

db -

getDatabase

public SQLiteDatabase getDatabase()

Return db

setCaptureExplainQueryPlan

public void setCaptureExplainQueryPlan(boolean captureExplainQueryPlan)

If turned on, explain query plan is run before executing a query and stored in lastExplainQueryPlan and also get logged

Parameters:

captureExplainQueryPlan - true to turn capture on and false to turn off

getLastExplainQueryPlan

public JSONObject getLastExplainQueryPlan()

Returns:

explain query plan for last query run (if captureExplainQueryPlan is true)

getDatabaseSize

public int getDatabaseSize()

Get database size

beginTransaction

public void beginTransaction()

Start transaction NB: to avoid deadlock, caller should have synchronized(store.getDatabase()) around the whole transaction

endTransaction

public void endTransaction()

End transaction (commit or rollback)

setTransactionSuccessful

public void setTransactionSuccessful()

Mark transaction as successful (next call to endTransaction will be a commit)

registerSoup

public void registerSoup(java.lang.String soupName,
                         IndexSpec[] indexSpecs)

Register a soup. Create table for soupName with a column for the soup itself and columns for paths specified in indexSpecs Create indexes on the new table to make lookup faster Create rows in soup index map table for indexSpecs

Parameters:

soupName -

indexSpecs -

registerSoupUsingTableName

protected void registerSoupUsingTableName(java.lang.String soupName,
                                          IndexSpec[] indexSpecs,
                                          java.lang.String soupTableName)

Helper method for registerSoup

Parameters:

soupName -

indexSpecs -

soupTableName -

resumeLongOperations

public void resumeLongOperations()

Finish long operations that were interrupted

getLongOperations

public LongOperation[] getLongOperations()

Returns:

unfinished long operations

alterSoup

public void alterSoup(java.lang.String soupName,
                      IndexSpec[] indexSpecs,
                      boolean reIndexData)
               throws JSONException

Alter soup using only soup name without extra soup features.

Parameters:

soupName -

indexSpecs - array of index specs

reIndexData -

Throws:

JSONException

reIndexSoup

public void reIndexSoup(java.lang.String soupName,
                        java.lang.String[] indexPaths,
                        boolean handleTx)

Re-index all soup elements for passed indexPaths NB: only indexPath that have IndexSpec on them will be indexed

Parameters:

soupName -

indexPaths -

handleTx -

getSoupIndexSpecs

public IndexSpec[] getSoupIndexSpecs(java.lang.String soupName)

Return indexSpecs of soup

Parameters:

soupName -

Returns:

hasIndexForPath

public boolean hasIndexForPath(java.lang.String soupName,
                               java.lang.String path)

Return true if the given path is indexed on the given soup

Parameters:

soupName -

path -

Returns:

clearSoup

public void clearSoup(java.lang.String soupName)

Clear all rows from a soup

Parameters:

soupName -

hasSoup

public boolean hasSoup(java.lang.String soupName)

Check if soup exists

Parameters:

soupName -

Returns:

true if soup exists, false otherwise

dropSoup

public void dropSoup(java.lang.String soupName)

Destroy a soup Drop table for soupName Cleanup entries in soup index map table

Parameters:

soupName -

dropAllSoups

public void dropAllSoups()

Destroy all the soups in the smartstore

getAllSoupNames

public java.util.List<java.lang.String> getAllSoupNames()

Returns:

all soup names in the smartstore

query

public JSONArray query(QuerySpec querySpec,
                       int pageIndex)
                throws JSONException

Run a query given by its query spec Returns results from selected page

Parameters:

querySpec - the query to run

pageIndex - the page to return

Throws:

JSONException

queryWithArgs

public JSONArray queryWithArgs(QuerySpec querySpec,
                               int pageIndex,
                               java.lang.String... whereArgs)
                        throws JSONException

Run a query given by its query spec with optional "where args" (i.e. bind args) Provided bind args will be substituted to the ? found in the query NB: Bind args are only supported for smart queries Returns results from selected page

Parameters:

querySpec - the query to run

pageIndex - the page to return

whereArgs - the bind args (optional - only supported for smart queries)

Throws:

JSONException

queryAsString

public void queryAsString(java.lang.StringBuilder resultBuilder,
                          QuerySpec querySpec,
                          int pageIndex)

Run a query given by its query Spec Returns results from selected page without deserializing any JSON

Parameters:

resultBuilder - string builder to which results are appended

querySpec -

pageIndex -

countQuery

public int countQuery(QuerySpec querySpec)

Parameters:

querySpec -

Returns:

count of results for a query

convertSmartSql

public java.lang.String convertSmartSql(java.lang.String smartSql)

Parameters:

smartSql -

Returns:

create

public JSONObject create(java.lang.String soupName,
                         JSONObject soupElt)
                  throws JSONException

Create (and commits) Note: Passed soupElt is modified (last modified date and soup entry id fields)

Parameters:

soupName -

soupElt -

Returns:

soupElt created or null if creation failed

Throws:

JSONException

create

public JSONObject create(java.lang.String soupName,
                         JSONObject soupElt,
                         boolean handleTx)
                  throws JSONException

Create Note: Passed soupElt is modified (last modified date and soup entry id fields)

Parameters:

soupName -

soupElt -

Returns:

Throws:

JSONException

retrieve

public JSONArray retrieve(java.lang.String soupName,
                          java.lang.Long... soupEntryIds)
                   throws JSONException

Retrieve

Parameters:

soupName -

soupEntryIds -

Returns:

JSONArray of JSONObject's with the given soupEntryIds

Throws:

JSONException

update

public JSONObject update(java.lang.String soupName,
                         JSONObject soupElt,
                         long soupEntryId)
                  throws JSONException

Update (and commits) Note: Passed soupElt is modified (last modified date and soup entry id fields)

Parameters:

soupName -

soupElt -

soupEntryId -

Returns:

soupElt updated or null if update failed

Throws:

JSONException

update

public JSONObject update(java.lang.String soupName,
                         JSONObject soupElt,
                         long soupEntryId,
                         boolean handleTx)
                  throws JSONException

Update Note: Passed soupElt is modified (last modified date and soup entry id fields)

Parameters:

soupName -

soupElt -

soupEntryId -

handleTx -

Returns:

Throws:

JSONException

upsert

public JSONObject upsert(java.lang.String soupName,
                         JSONObject soupElt,
                         java.lang.String externalIdPath)
                  throws JSONException

Upsert (and commits)

Parameters:

soupName -

soupElt -

externalIdPath -

Returns:

soupElt upserted or null if upsert failed

Throws:

JSONException

upsert

public JSONObject upsert(java.lang.String soupName,
                         JSONObject soupElt)
                  throws JSONException

Upsert (and commits) expecting _soupEntryId in soupElt for updates

Parameters:

soupName -

soupElt -

Returns:

Throws:

JSONException

upsert

public JSONObject upsert(java.lang.String soupName,
                         JSONObject soupElt,
                         java.lang.String externalIdPath,
                         boolean handleTx)
                  throws JSONException

Upsert

Parameters:

soupName -

soupElt -

externalIdPath -

handleTx -

Returns:

Throws:

JSONException

lookupSoupEntryId

public long lookupSoupEntryId(java.lang.String soupName,
                              java.lang.String fieldPath,
                              java.lang.String fieldValue)

Look for a soup element where fieldPath's value is fieldValue Return its soupEntryId Return -1 if not found Throw an exception if fieldName is not indexed Throw an exception if more than one soup element are found

Parameters:

soupName -

fieldPath -

fieldValue -

delete

public void delete(java.lang.String soupName,
                   java.lang.Long... soupEntryIds)

Delete soup elements given by their ids (and commits)

Parameters:

soupName -

soupEntryIds -

delete

public void delete(java.lang.String soupName,
                   java.lang.Long[] soupEntryIds,
                   boolean handleTx)

Delete soup elements given by their ids

Parameters:

soupName -

soupEntryIds -

handleTx -

deleteByQuery

public void deleteByQuery(java.lang.String soupName,
                          QuerySpec querySpec)

Delete soup elements selected by querySpec (and commits)

Parameters:

soupName -

querySpec - Query returning entries to delete (if querySpec uses smartSQL, it must select soup entry ids)

deleteByQuery

public void deleteByQuery(java.lang.String soupName,
                          QuerySpec querySpec,
                          boolean handleTx)

Delete soup elements selected by querySpec

Parameters:

soupName -

querySpec -

handleTx -

getFtsExtension

public SmartStore.FtsExtension getFtsExtension()

Returns:

ftsX to be used when creating the virtual table to support full_text queries

setFtsExtension

public void setFtsExtension(SmartStore.FtsExtension ftsExtension)

Sets the ftsX to be used when creating the virtual table to support full_text queries NB: only used in tests

Parameters:

ftsExtension -

getSoupTableName

public static java.lang.String getSoupTableName(long soupId)

Parameters:

soupId -

Returns:

project

public static java.lang.Object project(JSONObject soup,
                                       java.lang.String path)

Parameters:

soup -

path -

Returns:

object at path in soup Examples (in pseudo code): json = {"a": {"b": [{"c":"xx"}, {"c":"xy"}, {"d": [{"e":1}, {"e":2}]}, {"d": [{"e":3}, {"e":4}]}] }} projectIntoJson(jsonObj, "a") = {"b": [{"c":"xx"}, {"c":"xy"}, {"d": [{"e":1}, {"e":2}]}, {"d": [{"e":3}, {"e":4}]} ]} projectIntoJson(json, "a.b") = [{c:"xx"}, {c:"xy"}, {"d": [{"e":1}, {"e":2}]}, {"d": [{"e":3}, {"e":4}]}] projectIntoJson(json, "a.b.c") = ["xx", "xy"] // new in 4.1 projectIntoJson(json, "a.b.d") = [[{"e":1}, {"e":2}], [{"e":3}, {"e":4}]] // new in 4.1 projectIntoJson(json, "a.b.d.e") = [[1, 2], [3, 4]] // new in 4.1

projectReturningNULLObject

public static java.lang.Object projectReturningNULLObject(JSONObject soup,
                                                          java.lang.String path)

Same as project but returns JSONObject.NULL if node found but without value and null if node not found

Parameters:

soup -

path -

Returns:

updateTableNameAndAddColumns

public static void updateTableNameAndAddColumns(SQLiteDatabase db,
                                                java.lang.String oldName,
                                                java.lang.String newName,
                                                java.lang.String[] columns)

Updates the given table with a new name and adds columns if any.

Parameters:

db - Database to update

oldName - Old name of the table to be renamed, null if table should not be renamed.

newName - New name of the table to be renamed, null if table should not be renamed.

columns - Columns to add. Null if no new columns should be added.

getRuntimeSettings

public java.util.List<java.lang.String> getRuntimeSettings()

Get SQLCipher runtime settings

Returns:

list of SQLCipher runtime settings

getCompileOptions

public java.util.List<java.lang.String> getCompileOptions()

Get SQLCipher compile options

Returns:

list of SQLCipher compile options

getSQLCipherVersion

public java.lang.String getSQLCipherVersion()

Get SQLCipher version

Returns:

SQLCipher version