com.cloudant.sync.sqlite

Class SQLDatabase

java.lang.Object

com.cloudant.sync.sqlite.SQLDatabase

Direct Known Subclasses:

AndroidSQLite

public abstract class SQLDatabase
extends java.lang.Object

API Status: Private - API users are discouraged from using this class as fields, method signatures, and implementation details may be subject to change

Field Summary

Fields

Modifier and Type	Field and Description
static int	CONFLICT_ABORT When a constraint violation occurs,no ROLLBACK is executed so changes from prior commands within the same transaction are preserved.
static int	CONFLICT_FAIL When a constraint violation occurs, the command aborts with a return code SQLITE_CONSTRAINT.
static int	CONFLICT_IGNORE When a constraint violation occurs, the one row that contains the constraint violation is not inserted or changed.
static int	CONFLICT_NONE Use the following when no conflict action is specified.
static int	CONFLICT_REPLACE When a UNIQUE constraint violation occurs, the pre-existing rows that are causing the constraint violation are removed prior to inserting or updating the current row.
static int	CONFLICT_ROLLBACK When a constraint violation occurs, an immediate ROLLBACK occurs, thus ending the current transaction, and the command aborts with a return code of SQLITE_CONSTRAINT.
java.lang.String	filename

Constructor Summary

Constructors

Constructor and Description
SQLDatabase()

Method Summary

Modifier and Type	Method and Description
abstract void	beginTransaction() Begins a transaction in EXCLUSIVE mode.
abstract void	close() Close the database
abstract void	compactDatabase() For SQLite database, this is to call: this.execSQL("VACUUM");
abstract int	delete(java.lang.String table, java.lang.String whereClause, java.lang.String[] whereArgs) Convenience method for deleting rows in the database.
abstract void	endTransaction() End a transaction.
abstract void	execSQL(java.lang.String sql) Execute a single SQL statement that is NOT a SELECT or any other SQL statement that returns data.
abstract void	execSQL(java.lang.String sql, java.lang.Object[] bindArgs) Execute a single SQL statement that is NOT a SELECT/INSERT/UPDATE/DELETE.
abstract int	getVersion() Gets the database version, and SQLDatabase's version is defined as:
abstract long	insert(java.lang.String table, ContentValues values) Convenience method for inserting a row into the database.
abstract long	insertWithOnConflict(java.lang.String table, ContentValues initialValues, int conflictAlgorithm)
abstract boolean	isOpen()
abstract void	open() Open the database
abstract Cursor	rawQuery(java.lang.String sql, java.lang.String[] selectionArgs) Runs the provided SQL and returns a Cursor over the result set.
abstract void	setTransactionSuccessful() Marks the current transaction as successful.
abstract int	update(java.lang.String table, ContentValues values, java.lang.String whereClause, java.lang.String[] whereArgs) Convenience method for updating rows in the database.

Methods inherited from class java.lang.Object

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

Field Detail

filename

public java.lang.String filename

CONFLICT_ROLLBACK

public static final int CONFLICT_ROLLBACK

When a constraint violation occurs, an immediate ROLLBACK occurs, thus ending the current transaction, and the command aborts with a return code of SQLITE_CONSTRAINT. If no transaction is active (other than the implied transaction that is created on every command) then this algorithm works the same as ABORT.

See Also:

Constant Field Values

CONFLICT_ABORT

public static final int CONFLICT_ABORT

When a constraint violation occurs,no ROLLBACK is executed so changes from prior commands within the same transaction are preserved. This is the default behavior.

See Also:

Constant Field Values

CONFLICT_FAIL

public static final int CONFLICT_FAIL

When a constraint violation occurs, the command aborts with a return code SQLITE_CONSTRAINT. But any changes to the database that the command made prior to encountering the constraint violation are preserved and are not backed out.

See Also:

Constant Field Values

CONFLICT_IGNORE

public static final int CONFLICT_IGNORE

When a constraint violation occurs, the one row that contains the constraint violation is not inserted or changed. But the command continues executing normally. Other rows before and after the row that contained the constraint violation continue to be inserted or updated normally. No error is returned.

See Also:

Constant Field Values

CONFLICT_REPLACE

public static final int CONFLICT_REPLACE

When a UNIQUE constraint violation occurs, the pre-existing rows that are causing the constraint violation are removed prior to inserting or updating the current row. Thus the insert or update always occurs. The command continues executing normally. No error is returned. If a NOT NULL constraint violation occurs, the NULL value is replaced by the default value for that column. If the column has no default value, then the ABORT algorithm is used. If a CHECK constraint violation occurs then the IGNORE algorithm is used. When this conflict resolution strategy deletes rows in order to satisfy a constraint, it does not invoke delete triggers on those rows. This behavior might change in a future release.

See Also:

Constant Field Values

CONFLICT_NONE

public static final int CONFLICT_NONE

Use the following when no conflict action is specified.

See Also:

Constant Field Values

Constructor Detail

SQLDatabase

public SQLDatabase()

Method Detail

execSQL

public abstract void execSQL(java.lang.String sql,
                             java.lang.Object[] bindArgs)
                      throws java.sql.SQLException

Execute a single SQL statement that is NOT a SELECT/INSERT/UPDATE/DELETE.

Parameters:

sql - the SQL statement to be executed. Multiple statements separated by semicolons are not supported.

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

Throws:

java.sql.SQLException - if the SQL string is invalid

execSQL

public abstract void execSQL(java.lang.String sql)
                      throws java.sql.SQLException

Execute a single SQL statement that is NOT a SELECT or any other SQL statement that returns data.

Parameters:

sql - the SQL statement to be executed. Multiple statements separated by semicolons are not supported.

Throws:

java.sql.SQLException - if the SQL string is invalid

compactDatabase

public abstract void compactDatabase()

For SQLite database, this is to call: this.execSQL("VACUUM");

getVersion

public abstract int getVersion()

Gets the database version, and SQLDatabase's version is defined as:

    PRAGMA user_version;

Returns:

the database version

See Also:

SQLite user_version

open

public abstract void open()

Open the database

close

public abstract void close()

Close the database

isOpen

public abstract boolean isOpen()

Returns:

true if the database is open

beginTransaction

public abstract void beginTransaction()

Begins a transaction in EXCLUSIVE mode.

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 abstract void endTransaction()

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

setTransactionSuccessful

public abstract 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:

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

update

public abstract int update(java.lang.String table,
                           ContentValues values,
                           java.lang.String whereClause,
                           java.lang.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

rawQuery

public abstract Cursor rawQuery(java.lang.String sql,
                                java.lang.String[] selectionArgs)
                         throws java.sql.SQLException

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. Note that Cursors are not synchronized, see the documentation for more details.

Throws:

java.sql.SQLException

delete

public abstract int delete(java.lang.String table,
                           java.lang.String whereClause,
                           java.lang.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. And, do not include "where" in the clause.

Returns:

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

insert

public abstract long insert(java.lang.String table,
                            ContentValues values)

Convenience method for inserting a row into the database.

Parameters:

table - the table to insert the row into

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

insertWithOnConflict

public abstract long insertWithOnConflict(java.lang.String table,
                                          ContentValues initialValues,
                                          int conflictAlgorithm)

Parameters:

table -

initialValues -

conflictAlgorithm -

Returns:

the row ID of the newly inserted row OR the primary key of the existing row if the input param 'conflictAlgorithm' = CONFLICT_IGNORE OR -1 if any error