android.database.sqlite
Class SQLiteDatabase

java.lang.Object
  android.database.sqlite.SQLiteClosable
      android.database.sqlite.SQLiteDatabase

public class SQLiteDatabase
extends SQLiteClosable

Exposes methods to manage a SQLite database.

SQLiteDatabase has methods to create, delete, execute SQL commands, and perform other common database management tasks.

See the Notepad sample application in the SDK for an example of creating and managing a database.

Database names must be unique within an application, not across all applications.

Localized Collation - ORDER BY

In addition to SQLite's default BINARY collator, Android supplies two more, LOCALIZED, which changes with the system's current locale if you wire it up correctly (XXX a link needed!), and UNICODE, which is the Unicode Collation Algorithm and not tailored to the current locale.

Nested Class Summary

static class	SQLiteDatabase.ConflictAlgorithm Algorithms used in ON CONFLICT clause http://www.sqlite.org/lang_conflict.html
static interface	SQLiteDatabase.CursorFactory Used to allow returning sub-classes of Cursor when calling query.

Field Summary

static int	CREATE_IF_NECESSARY Flag for openDatabase(java.lang.String, android.database.sqlite.SQLiteDatabase.CursorFactory, int) to create the database file if it does not already exist.
(package private) int	mNativeHandle Used by native code, do not rename
(package private) int	mTempTableSequence Used to make temp table names unique
static int	NO_LOCALIZED_COLLATORS Flag for openDatabase(java.lang.String, android.database.sqlite.SQLiteDatabase.CursorFactory, int) to open the database without support for localized collators.
static int	OPEN_READONLY Flag for openDatabase(java.lang.String, android.database.sqlite.SQLiteDatabase.CursorFactory, int) to open the database for reading only.
static int	OPEN_READWRITE Flag for openDatabase(java.lang.String, android.database.sqlite.SQLiteDatabase.CursorFactory, int) to open the database for reading and writing.
static int	SQLITE_MAX_LIKE_PATTERN_LENGTH Maximum Length Of A LIKE Or GLOB Pattern The pattern matching algorithm used in the default LIKE and GLOB implementation of SQLite can exhibit O(N^2) performance (where N is the number of characters in the pattern) for certain pathological cases.

Method Summary

(package private) void	addSQLiteClosable(SQLiteClosable closable)
void	beginTransaction() Begins a transaction.
void	close() Close the database.
SQLiteStatement	compileStatement(String sql) Compiles an SQL statement into a reusable pre-compiled statement object.
static SQLiteDatabase	create(SQLiteDatabase.CursorFactory factory) Create a memory backed SQLite database.
int	delete(String table, String whereClause, String[] whereArgs) Convenience method for deleting rows in the database.
void	endTransaction() End a transaction.
void	execSQL(String sql) Execute a single SQL statement that is not a query.
void	execSQL(String sql, Object[] bindArgs) Execute a single SQL statement that is not a query.
protected void	finalize() Is called before the object's memory is being reclaimed by the VM.
static String	findEditTable(String tables) Finds the name of the first table, which is editable.
long	getMaximumSize() Returns the maximum size the database may grow to.
long	getPageSize() Returns the maximum size the database may grow to.
String	getPath() Getter for the path to the database file.
Map<String,String>	getSyncedTables()
int	getVersion() Gets the database version.
long	insert(String table, String nullColumnHack, ContentValues values) Convenience method for inserting a row into the database.
long	insertOrThrow(String table, String nullColumnHack, ContentValues values) Convenience method for inserting a row into the database.
long	insertWithOnConflict(String table, String nullColumnHack, ContentValues initialValues, SQLiteDatabase.ConflictAlgorithm algorithm) General method for inserting a row into the database.
boolean	inTransaction() return true if there is a transaction pending
boolean	isDbLockedByCurrentThread() Checks if the database lock is held by this thread.
boolean	isDbLockedByOtherThreads() Checks if the database is locked by another thread.
boolean	isOpen()
boolean	isReadOnly() return whether the DB is opened as read only.
(package private) int	lastChangeCount() Returns the number of changes made in the last statement executed.
(package private) long	lastInsertRow() Returns the row ID of the last row inserted into the database.
(package private) void	lock() Locks the database for exclusive access.
void	markTableSyncable(String table, String deletedTable) Mark this table as syncable.
void	markTableSyncable(String table, String foreignKey, String updateTable) Mark this table as syncable, with the _sync_dirty residing in another table.
(package private) void	native_execSQL(String sql) Native call to execute a raw SQL statement.
(package private) void	native_setLocale(String loc, int flags) Native call to set the locale.
boolean	needUpgrade(int newVersion)
protected void	onAllReferencesReleased()
(package private) void	onCorruption()
static SQLiteDatabase	openDatabase(String path, SQLiteDatabase.CursorFactory factory, int flags) Open the database according to the flags OPEN_READWRITE OPEN_READONLY CREATE_IF_NECESSARY and/or NO_LOCALIZED_COLLATORS.
static SQLiteDatabase	openOrCreateDatabase(File file, SQLiteDatabase.CursorFactory factory) Equivalent to openDatabase(file.getPath(), factory, CREATE_IF_NECESSARY).
static SQLiteDatabase	openOrCreateDatabase(String path, SQLiteDatabase.CursorFactory factory) Equivalent to openDatabase(path, factory, CREATE_IF_NECESSARY).
Cursor	query(boolean distinct, String table, String[] columns, String selection, String[] selectionArgs, String groupBy, String having, String orderBy, String limit) Query the given URL, returning a Cursor over the result set.
Cursor	query(String table, String[] columns, String selection, String[] selectionArgs, String groupBy, String having, String orderBy) Query the given table, returning a Cursor over the result set.
Cursor	query(String table, String[] columns, String selection, String[] selectionArgs, String groupBy, String having, String orderBy, String limit) Query the given table, returning a Cursor over the result set.
Cursor	queryWithFactory(SQLiteDatabase.CursorFactory cursorFactory, boolean distinct, String table, String[] columns, String selection, String[] selectionArgs, String groupBy, String having, String orderBy, String limit) Query the given URL, returning a Cursor over the result set.
Cursor	rawQuery(String sql, String[] selectionArgs) Runs the provided SQL and returns a Cursor over the result set.
Cursor	rawQuery(String sql, String[] selectionArgs, int initialRead, int maxRead) Runs the provided SQL and returns a cursor over the result set.
Cursor	rawQueryWithFactory(SQLiteDatabase.CursorFactory cursorFactory, String sql, String[] selectionArgs, String editTable) Runs the provided SQL and returns a cursor over the result set.
static int	releaseMemory() Attempts to release memory that SQLite holds but does not require to operate properly.
(package private) void	removeSQLiteClosable(SQLiteClosable closable)
long	replace(String table, String nullColumnHack, ContentValues initialValues) Convenience method for replacing a row in the database.
long	replaceOrThrow(String table, String nullColumnHack, ContentValues initialValues) Convenience method for replacing a row in the database.
(package private) void	rowUpdated(String table, long rowId) Call for each row that is updated in a cursor.
void	setLocale(Locale locale) Sets the locale for this database.
void	setLockingEnabled(boolean lockingEnabled) Control whether or not the SQLiteDatabase is made thread-safe by using locks around critical sections.
long	setMaximumSize(long numBytes) Sets the maximum size the database will grow to.
void	setPageSize(long numBytes) Sets the database page size.
void	setTransactionSuccessful() Marks the current transaction as successful.
void	setVersion(int version) Sets the database version.
(package private) void	unlock() Releases the database lock.
int	update(String table, ContentValues values, String whereClause, String[] whereArgs) Convenience method for updating rows in the database.
int	updateWithOnConflict(String table, ContentValues values, String whereClause, String[] whereArgs, SQLiteDatabase.ConflictAlgorithm algorithm) Convenience method for updating rows in the database.
boolean	yieldIfContended() Deprecated. if the db is locked more than once (becuase of nested transactions) then the lock will not be yielded. Use yieldIfContendedSafely instead.
boolean	yieldIfContendedSafely() Temporarily end the transaction to let other threads run.

Methods inherited from class android.database.sqlite.SQLiteClosable

acquireReference, onAllReferencesReleasedFromContainer, releaseReference, releaseReferenceFromContainer

Methods inherited from class java.lang.Object

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

Field Detail

SQLITE_MAX_LIKE_PATTERN_LENGTH

public static final int SQLITE_MAX_LIKE_PATTERN_LENGTH

Maximum Length Of A LIKE Or GLOB Pattern The pattern matching algorithm used in the default LIKE and GLOB implementation of SQLite can exhibit O(N^2) performance (where N is the number of characters in the pattern) for certain pathological cases. To avoid denial-of-service attacks the length of the LIKE or GLOB pattern is limited to SQLITE_MAX_LIKE_PATTERN_LENGTH bytes. The default value of this limit is 50000. A modern workstation can evaluate even a pathological LIKE or GLOB pattern of 50000 bytes relatively quickly. The denial of service problem only comes into play when the pattern length gets into millions of bytes. Nevertheless, since most useful LIKE or GLOB patterns are at most a few dozen bytes in length, paranoid application developers may want to reduce this parameter to something in the range of a few hundred if they know that external users are able to generate arbitrary patterns.

See Also:

Constant Field Values

OPEN_READWRITE

public static final int OPEN_READWRITE

Flag for openDatabase(java.lang.String, android.database.sqlite.SQLiteDatabase.CursorFactory, int) to open the database for reading and writing. If the disk is full, this may fail even before you actually write anything. Note that the value of this flag is 0, so it is the default.

See Also:

Constant Field Values

OPEN_READONLY

public static final int OPEN_READONLY

Flag for openDatabase(java.lang.String, android.database.sqlite.SQLiteDatabase.CursorFactory, int) to open the database for reading only. This is the only reliable way to open a database if the disk may be full.

See Also:

Constant Field Values

NO_LOCALIZED_COLLATORS

public static final int NO_LOCALIZED_COLLATORS

Flag for openDatabase(java.lang.String, android.database.sqlite.SQLiteDatabase.CursorFactory, int) to open the database without support for localized collators. This causes the collator LOCALIZED not to be created. You must be consistent when using this flag to use the setting the database was created with. If this is set, setLocale(java.util.Locale) will do nothing.

See Also:

Constant Field Values

CREATE_IF_NECESSARY

public static final int CREATE_IF_NECESSARY

Flag for openDatabase(java.lang.String, android.database.sqlite.SQLiteDatabase.CursorFactory, int) to create the database file if it does not already exist.

See Also:

Constant Field Values

mNativeHandle

int mNativeHandle

Used by native code, do not rename

mTempTableSequence

int mTempTableSequence

Used to make temp table names unique

Method Detail

addSQLiteClosable

void addSQLiteClosable(SQLiteClosable closable)

Parameters:

closable -

removeSQLiteClosable

void removeSQLiteClosable(SQLiteClosable closable)

onAllReferencesReleased

protected void onAllReferencesReleased()

Specified by:

onAllReferencesReleased in class SQLiteClosable

releaseMemory

public static int releaseMemory()

Attempts to release memory that SQLite holds but does not require to operate properly. Typically this memory will come from the page cache.

Returns:

the number of bytes actually released

setLockingEnabled

public void setLockingEnabled(boolean lockingEnabled)

Control whether or not the SQLiteDatabase is made thread-safe by using locks around critical sections. This is pretty expensive, so if you know that your DB will only be used by a single thread then you should set this to false. The default is true.

Parameters:

lockingEnabled - set to true to enable locks, false otherwise

onCorruption

void onCorruption()

lock

void lock()

Locks the database for exclusive access. The database lock must be held when touch the native sqlite3* object since it is single threaded and uses a polling lock contention algorithm. The lock is recursive, and may be acquired multiple times by the same thread. This is a no-op if mLockingEnabled is false.

See Also:

unlock()

unlock

void unlock()

Releases the database lock. This is a no-op if mLockingEnabled is false.

See Also:

unlock()

beginTransaction

public void beginTransaction()

Begins a transaction. Transactions can be nested. When the outer transaction is ended all of the work done in that transaction and all of the nested transactions will be committed or rolled back. The changes will be rolled back if any transaction is ended without being marked as clean (by calling setTransactionSuccessful). Otherwise they will be committed.

Here is the standard idiom for transactions:

   db.beginTransaction();
   try {
     ...
     db.setTransactionSuccessful();
   } finally {
     db.endTransaction();
   }
 

endTransaction

public void endTransaction()

End a transaction. See beginTransaction for notes about how to use this and when transactions are committed and rolled back.

setTransactionSuccessful

public void setTransactionSuccessful()

Marks the current transaction as successful. Do not do any more database work between calling this and calling endTransaction. Do as little non-database work as possible in that situation too. If any errors are encountered between this and endTransaction the transaction will still be committed.

Throws:

IllegalStateException - if the current thread is not in a transaction or the transaction is already marked as successful.

inTransaction

public boolean inTransaction()

return true if there is a transaction pending

isDbLockedByCurrentThread

public boolean isDbLockedByCurrentThread()

Checks if the database lock is held by this thread.

Returns:

true, if this thread is holding the database lock.

isDbLockedByOtherThreads

public boolean isDbLockedByOtherThreads()

Checks if the database is locked by another thread. This is just an estimate, since this status can change at any time, including after the call is made but before the result has been acted upon.

Returns:

true, if the database is locked by another thread

yieldIfContended

public boolean yieldIfContended()

Deprecated. if the db is locked more than once (becuase of nested transactions) then the lock will not be yielded. Use yieldIfContendedSafely instead.

Temporarily end the transaction to let other threads run. The transaction is assumed to be successful so far. Do not call setTransactionSuccessful before calling this. When this returns a new transaction will have been created but not marked as successful.

Returns:

true if the transaction was yielded

yieldIfContendedSafely

public boolean yieldIfContendedSafely()

Temporarily end the transaction to let other threads run. The transaction is assumed to be successful so far. Do not call setTransactionSuccessful before calling this. When this returns a new transaction will have been created but not marked as successful. This assumes that there are no nested transactions (beginTransaction has only been called once) and will through an exception if that is not the case.

Returns:

true if the transaction was yielded

getSyncedTables

public Map<String,String> getSyncedTables()

openDatabase

public static SQLiteDatabase openDatabase(String path,
                                          SQLiteDatabase.CursorFactory factory,
                                          int flags)

Open the database according to the flags OPEN_READWRITE OPEN_READONLY CREATE_IF_NECESSARY and/or NO_LOCALIZED_COLLATORS.

Sets the locale of the database to the the system's current locale. Call setLocale(java.util.Locale) if you would like something else.

Parameters:

path - to database file to open and/or create

factory - an optional factory class that is called to instantiate a cursor when query is called, or null for default

flags - to control database access mode

Returns:

the newly opened database

Throws:

SQLiteException - if the database cannot be opened

openOrCreateDatabase

public static SQLiteDatabase openOrCreateDatabase(File file,
                                                  SQLiteDatabase.CursorFactory factory)

Equivalent to openDatabase(file.getPath(), factory, CREATE_IF_NECESSARY).

openOrCreateDatabase

public static SQLiteDatabase openOrCreateDatabase(String path,
                                                  SQLiteDatabase.CursorFactory factory)

Equivalent to openDatabase(path, factory, CREATE_IF_NECESSARY).

create

public static SQLiteDatabase create(SQLiteDatabase.CursorFactory factory)

Create a memory backed SQLite database. Its contents will be destroyed when the database is closed.

Sets the locale of the database to the the system's current locale. Call setLocale(java.util.Locale) if you would like something else.

Parameters:

factory - an optional factory class that is called to instantiate a cursor when query is called

Returns:

a SQLiteDatabase object, or null if the database can't be created

close

public void close()

Close the database.

getVersion

public int getVersion()

Gets the database version.

Returns:

the database version

setVersion

public void setVersion(int version)

Sets the database version.

Parameters:

version - the new database version

getMaximumSize

public long getMaximumSize()

Returns the maximum size the database may grow to.

Returns:

the new maximum database size

setMaximumSize

public long setMaximumSize(long numBytes)

Sets the maximum size the database will grow to. The maximum size cannot be set below the current size.

Parameters:

numBytes - the maximum database size, in bytes

Returns:

the new maximum database size

getPageSize

public long getPageSize()

Returns the maximum size the database may grow to.

Returns:

the new maximum database size

setPageSize

public void setPageSize(long numBytes)

Sets the database page size. The page size must be a power of two. This method does not work if any data has been written to the database file, and must be called right after the database has been created.

Parameters:

numBytes - the database page size, in bytes

markTableSyncable

public void markTableSyncable(String table,
                              String deletedTable)

Mark this table as syncable. When an update occurs in this table the _sync_dirty field will be set to ensure proper syncing operation.

Parameters:

table - the table to mark as syncable

deletedTable - The deleted table that corresponds to the syncable table

markTableSyncable

public void markTableSyncable(String table,
                              String foreignKey,
                              String updateTable)

Mark this table as syncable, with the _sync_dirty residing in another table. When an update occurs in this table the _sync_dirty field of the row in updateTable with the _id in foreignKey will be set to ensure proper syncing operation.

Parameters:

table - an update on this table will trigger a sync time removal

foreignKey - this is the column in table whose value is an _id in updateTable

updateTable - this is the table that will have its _sync_dirty

rowUpdated

void rowUpdated(String table,
                long rowId)

Call for each row that is updated in a cursor.

Parameters:

table - the table the row is in

rowId - the row ID of the updated row

findEditTable

public static String findEditTable(String tables)

Finds the name of the first table, which is editable.

Parameters:

tables - a list of tables

Returns:

the first table listed

compileStatement

public SQLiteStatement compileStatement(String sql)
                                 throws SQLException

Compiles an SQL statement into a reusable pre-compiled statement object. The parameters are identical to execSQL(String). You may put ?s in the statement and fill in those values with SQLiteProgram.bindString(int, java.lang.String) and SQLiteProgram.bindLong(int, long) each time you want to run the statement. Statements may not return result sets larger than 1x1.

Parameters:

sql - The raw SQL statement, may contain ? for unknown values to be bound later.

Returns:

a pre-compiled statement object.

Throws:

SQLException

query

public Cursor query(boolean distinct,
                    String table,
                    String[] columns,
                    String selection,
                    String[] selectionArgs,
                    String groupBy,
                    String having,
                    String orderBy,
                    String limit)

Query the given URL, returning a Cursor over the result set.

Parameters:

distinct - true if you want each row to be unique, false otherwise.

table - The table name to compile the query against.

columns - A list of which columns to return. Passing null will return all columns, which is discouraged to prevent reading data from storage that isn't going to be used.

selection - A filter declaring which rows to return, formatted as an SQL WHERE clause (excluding the WHERE itself). Passing null will return all rows for the given table.

selectionArgs - You may include ?s in selection, which will be replaced by the values from selectionArgs, in order that they appear in the selection. The values will be bound as Strings.

groupBy - A filter declaring how to group rows, formatted as an SQL GROUP BY clause (excluding the GROUP BY itself). Passing null will cause the rows to not be grouped.

having - A filter declare which row groups to include in the cursor, if row grouping is being used, formatted as an SQL HAVING clause (excluding the HAVING itself). Passing null will cause all row groups to be included, and is required when row grouping is not being used.

orderBy - How to order the rows, formatted as an SQL ORDER BY clause (excluding the ORDER BY itself). Passing null will use the default sort order, which may be unordered.

limit - Limits the number of rows returned by the query, formatted as LIMIT clause. Passing null denotes no LIMIT clause.

Returns:

A Cursor object, which is positioned before the first entry

See Also:

Cursor

queryWithFactory

public Cursor queryWithFactory(SQLiteDatabase.CursorFactory cursorFactory,
                               boolean distinct,
                               String table,
                               String[] columns,
                               String selection,
                               String[] selectionArgs,
                               String groupBy,
                               String having,
                               String orderBy,
                               String limit)

Query the given URL, returning a Cursor over the result set.

Parameters:

cursorFactory - the cursor factory to use, or null for the default factory

distinct - true if you want each row to be unique, false otherwise.

table - The table name to compile the query against.

columns - A list of which columns to return. Passing null will return all columns, which is discouraged to prevent reading data from storage that isn't going to be used.

selection - A filter declaring which rows to return, formatted as an SQL WHERE clause (excluding the WHERE itself). Passing null will return all rows for the given table.

selectionArgs - You may include ?s in selection, which will be replaced by the values from selectionArgs, in order that they appear in the selection. The values will be bound as Strings.

groupBy - A filter declaring how to group rows, formatted as an SQL GROUP BY clause (excluding the GROUP BY itself). Passing null will cause the rows to not be grouped.

having - A filter declare which row groups to include in the cursor, if row grouping is being used, formatted as an SQL HAVING clause (excluding the HAVING itself). Passing null will cause all row groups to be included, and is required when row grouping is not being used.

orderBy - How to order the rows, formatted as an SQL ORDER BY clause (excluding the ORDER BY itself). Passing null will use the default sort order, which may be unordered.

limit - Limits the number of rows returned by the query, formatted as LIMIT clause. Passing null denotes no LIMIT clause.

Returns:

A Cursor object, which is positioned before the first entry

See Also:

Cursor

query

public Cursor query(String table,
                    String[] columns,
                    String selection,
                    String[] selectionArgs,
                    String groupBy,
                    String having,
                    String orderBy)

Query the given table, returning a Cursor over the result set.

Parameters:

table - The table name to compile the query against.

columns - A list of which columns to return. Passing null will return all columns, which is discouraged to prevent reading data from storage that isn't going to be used.

selection - A filter declaring which rows to return, formatted as an SQL WHERE clause (excluding the WHERE itself). Passing null will return all rows for the given table.

selectionArgs - You may include ?s in selection, which will be replaced by the values from selectionArgs, in order that they appear in the selection. The values will be bound as Strings.

groupBy - A filter declaring how to group rows, formatted as an SQL GROUP BY clause (excluding the GROUP BY itself). Passing null will cause the rows to not be grouped.

having - A filter declare which row groups to include in the cursor, if row grouping is being used, formatted as an SQL HAVING clause (excluding the HAVING itself). Passing null will cause all row groups to be included, and is required when row grouping is not being used.

orderBy - How to order the rows, formatted as an SQL ORDER BY clause (excluding the ORDER BY itself). Passing null will use the default sort order, which may be unordered.

Returns:

A Cursor object, which is positioned before the first entry

See Also:

Cursor

query

public Cursor query(String table,
                    String[] columns,
                    String selection,
                    String[] selectionArgs,
                    String groupBy,
                    String having,
                    String orderBy,
                    String limit)

Query the given table, returning a Cursor over the result set.

Parameters:

table - The table name to compile the query against.

columns - A list of which columns to return. Passing null will return all columns, which is discouraged to prevent reading data from storage that isn't going to be used.

selection - A filter declaring which rows to return, formatted as an SQL WHERE clause (excluding the WHERE itself). Passing null will return all rows for the given table.

selectionArgs - You may include ?s in selection, which will be replaced by the values from selectionArgs, in order that they appear in the selection. The values will be bound as Strings.

groupBy - A filter declaring how to group rows, formatted as an SQL GROUP BY clause (excluding the GROUP BY itself). Passing null will cause the rows to not be grouped.

having - A filter declare which row groups to include in the cursor, if row grouping is being used, formatted as an SQL HAVING clause (excluding the HAVING itself). Passing null will cause all row groups to be included, and is required when row grouping is not being used.

orderBy - How to order the rows, formatted as an SQL ORDER BY clause (excluding the ORDER BY itself). Passing null will use the default sort order, which may be unordered.

limit - Limits the number of rows returned by the query, formatted as LIMIT clause. Passing null denotes no LIMIT clause.

Returns:

A Cursor object, which is positioned before the first entry

See Also:

Cursor

rawQuery

public Cursor rawQuery(String sql,
                       String[] selectionArgs)

Runs the provided SQL and returns a Cursor over the result set.

Parameters:

sql - the SQL query. The SQL string must not be ; terminated

selectionArgs - You may include ?s in where clause in the query, which will be replaced by the values from selectionArgs. The values will be bound as Strings.

Returns:

A Cursor object, which is positioned before the first entry

rawQueryWithFactory

public Cursor rawQueryWithFactory(SQLiteDatabase.CursorFactory cursorFactory,
                                  String sql,
                                  String[] selectionArgs,
                                  String editTable)

Runs the provided SQL and returns a cursor over the result set.

Parameters:

cursorFactory - the cursor factory to use, or null for the default factory

sql - the SQL query. The SQL string must not be ; terminated

selectionArgs - You may include ?s in where clause in the query, which will be replaced by the values from selectionArgs. The values will be bound as Strings.

editTable - the name of the first table, which is editable

Returns:

A Cursor object, which is positioned before the first entry

rawQuery

public Cursor rawQuery(String sql,
                       String[] selectionArgs,
                       int initialRead,
                       int maxRead)

Runs the provided SQL and returns a cursor over the result set. The cursor will read an initial set of rows and the return to the caller. It will continue to read in batches and send data changed notifications when the later batches are ready.

Parameters:

sql - the SQL query. The SQL string must not be ; terminated

selectionArgs - You may include ?s in where clause in the query, which will be replaced by the values from selectionArgs. The values will be bound as Strings.

initialRead - set the initial count of items to read from the cursor

maxRead - set the count of items to read on each iteration after the first

Returns:

A Cursor object, which is positioned before the first entry

insert

public long insert(String table,
                   String nullColumnHack,
                   ContentValues values)

Convenience method for inserting a row into the database.

Parameters:

table - the table to insert the row into

nullColumnHack - SQL doesn't allow inserting a completely empty row, so if initialValues is empty this column will explicitly be assigned a NULL value

values - this map contains the initial column values for the row. The keys should be the column names and the values the column values

Returns:

the row ID of the newly inserted row, or -1 if an error occurred

insertOrThrow

public long insertOrThrow(String table,
                          String nullColumnHack,
                          ContentValues values)
                   throws SQLException

Convenience method for inserting a row into the database.

Parameters:

table - the table to insert the row into

nullColumnHack - SQL doesn't allow inserting a completely empty row, so if initialValues is empty this column will explicitly be assigned a NULL value

values - this map contains the initial column values for the row. The keys should be the column names and the values the column values

Returns:

the row ID of the newly inserted row, or -1 if an error occurred

Throws:

SQLException

replace

public long replace(String table,
                    String nullColumnHack,
                    ContentValues initialValues)

Convenience method for replacing a row in the database.

Parameters:

table - the table in which to replace the row

nullColumnHack - SQL doesn't allow inserting a completely empty row, so if initialValues is empty this row will explicitly be assigned a NULL value

initialValues - this map contains the initial column values for the row. The key

Returns:

the row ID of the newly inserted row, or -1 if an error occurred

replaceOrThrow

public long replaceOrThrow(String table,
                           String nullColumnHack,
                           ContentValues initialValues)
                    throws SQLException

Convenience method for replacing a row in the database.

Parameters:

table - the table in which to replace the row

nullColumnHack - SQL doesn't allow inserting a completely empty row, so if initialValues is empty this row will explicitly be assigned a NULL value

initialValues - this map contains the initial column values for the row. The key

Returns:

the row ID of the newly inserted row, or -1 if an error occurred

Throws:

SQLException

insertWithOnConflict

public long insertWithOnConflict(String table,
                                 String nullColumnHack,
                                 ContentValues initialValues,
                                 SQLiteDatabase.ConflictAlgorithm algorithm)

General method for inserting a row into the database.

Parameters:

table - the table to insert the row into

nullColumnHack - SQL doesn't allow inserting a completely empty row, so if initialValues is empty this column will explicitly be assigned a NULL value

initialValues - this map contains the initial column values for the row. The keys should be the column names and the values the column values

algorithm - SQLiteDatabase.ConflictAlgorithm for insert conflict resolver

Returns:

the row ID of the newly inserted row, or -1 if an error occurred

delete

public int delete(String table,
                  String whereClause,
                  String[] whereArgs)

Convenience method for deleting rows in the database.

Parameters:

table - the table to delete from

whereClause - the optional WHERE clause to apply when deleting. Passing null will delete all rows.

Returns:

the number of rows affected if a whereClause is passed in, 0 otherwise. To remove all rows and get a count pass "1" as the whereClause.

update

public int update(String table,
                  ContentValues values,
                  String whereClause,
                  String[] whereArgs)

Convenience method for updating rows in the database.

Parameters:

table - the table to update in

values - a map from column names to new column values. null is a valid value that will be translated to NULL.

whereClause - the optional WHERE clause to apply when updating. Passing null will update all rows.

Returns:

the number of rows affected

updateWithOnConflict

public int updateWithOnConflict(String table,
                                ContentValues values,
                                String whereClause,
                                String[] whereArgs,
                                SQLiteDatabase.ConflictAlgorithm algorithm)

Convenience method for updating rows in the database.

Parameters:

table - the table to update in

values - a map from column names to new column values. null is a valid value that will be translated to NULL.

whereClause - the optional WHERE clause to apply when updating. Passing null will update all rows.

algorithm - SQLiteDatabase.ConflictAlgorithm for update conflict resolver

Returns:

the number of rows affected

execSQL

public void execSQL(String sql)
             throws SQLException

Execute a single SQL statement that is not a query. For example, CREATE TABLE, DELETE, INSERT, etc. Multiple statements separated by ;s are not supported. it takes a write lock

Throws:

SQLException - If the SQL string is invalid for some reason

execSQL

public void execSQL(String sql,
                    Object[] bindArgs)
             throws SQLException

Execute a single SQL statement that is not a query. For example, CREATE TABLE, DELETE, INSERT, etc. Multiple statements separated by ;s are not supported. it takes a write lock,

Parameters:

sql -

bindArgs - only byte[], String, Long and Double are supported in bindArgs.

Throws:

SQLException - If the SQL string is invalid for some reason

finalize

protected void finalize()

Description copied from class: Object

Is called before the object's memory is being reclaimed by the VM. This can only happen once the VM has detected, during a run of the garbage collector, that the object is no longer reachable by any thread of the running application.

The method can be used to free system resources or perform other cleanup before the object is garbage collected. The default implementation of the method is empty, which is also expected by the VM, but subclasses can override finalize() as required. Uncaught exceptions which are thrown during the execution of this method cause it to terminate immediately but are otherwise ignored.

Note that the VM does guarantee that finalize() is called at most once for any object, but it doesn't guarantee when (if at all) finalize() will be called. For example, object B's finalize() can delay the execution of object A's finalize() method and therefore it can delay the reclamation of A's memory. To be safe, use a ReferenceQueue, because it provides more control over the way the VM deals with references during garbage collection.

Overrides:

finalize in class Object

isReadOnly

public boolean isReadOnly()

return whether the DB is opened as read only.

Returns:

true if DB is opened as read only

isOpen

public boolean isOpen()

Returns:

true if the DB is currently open (has not been closed)

needUpgrade

public boolean needUpgrade(int newVersion)

getPath

public final String getPath()

Getter for the path to the database file.

Returns:

the path to our database file.

setLocale

public void setLocale(Locale locale)

Sets the locale for this database. Does nothing if this database has the NO_LOCALIZED_COLLATORS flag set or was opened read only.

Throws:

SQLException - if the locale could not be set. The most common reason for this is that there is no collator available for the locale you requested. In this case the database remains unchanged.

native_execSQL

void native_execSQL(String sql)
              throws SQLException

Native call to execute a raw SQL statement. mLock must be held when calling this method.

Parameters:

sql - The raw SQL string

Throws:

SQLException

native_setLocale

void native_setLocale(String loc,
                      int flags)

Native call to set the locale. mLock must be held when calling this method.

Throws:

SQLException

lastInsertRow

long lastInsertRow()

Returns the row ID of the last row inserted into the database.

Returns:

the row ID of the last row inserted into the database.

lastChangeCount

int lastChangeCount()

Returns the number of changes made in the last statement executed.

Returns:

the number of changes made in the last statement executed.