com.squareup.sqlbrite3

Class BriteDatabase

java.lang.Object

com.squareup.sqlbrite3.BriteDatabase

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

public final class BriteDatabase
extends java.lang.Object
implements java.io.Closeable

A lightweight wrapper around SupportSQLiteOpenHelper which allows for continuously observing the result of a query. Create using a SqlBrite instance.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	BriteDatabase.Transaction An in-progress database transaction.

Method Summary

Modifier and Type	Method and Description
void	close() Close the underlying SupportSQLiteOpenHelper and remove cached readable and writeable databases.
QueryObservable	createQuery(java.lang.Iterable<java.lang.String> tables, java.lang.String sql, java.lang.Object... args) See createQuery(String, String, Object...) for usage.
QueryObservable	createQuery(java.lang.Iterable<java.lang.String> tables, SupportSQLiteQuery query) See createQuery(String, SupportSQLiteQuery) for usage.
QueryObservable	createQuery(java.lang.String table, java.lang.String sql, java.lang.Object... args) Create an observable which will notify subscribers with a query for execution.
QueryObservable	createQuery(java.lang.String table, SupportSQLiteQuery query) Create an observable which will notify subscribers with a query for execution.
int	delete(java.lang.String table, java.lang.String whereClause, java.lang.String... whereArgs) Delete rows from the specified table and notify any subscribed queries.
void	execute(java.lang.String sql) Execute sql provided it is NOT a SELECT or any other SQL statement that returns data.
void	execute(java.lang.String sql, java.lang.Object... args) Execute sql provided it is NOT a SELECT or any other SQL statement that returns data.
void	executeAndTrigger(java.util.Set<java.lang.String> tables, java.lang.String sql) See executeAndTrigger(String, String) for usage.
void	executeAndTrigger(java.util.Set<java.lang.String> tables, java.lang.String sql, java.lang.Object... args) See executeAndTrigger(String, String, Object...) for usage.
void	executeAndTrigger(java.lang.String table, java.lang.String sql) Execute sql provided it is NOT a SELECT or any other SQL statement that returns data.
void	executeAndTrigger(java.lang.String table, java.lang.String sql, java.lang.Object... args) Execute sql provided it is NOT a SELECT or any other SQL statement that returns data.
long	executeInsert(java.util.Set<java.lang.String> tables, SupportSQLiteStatement statement) See executeInsert(String, SupportSQLiteStatement) for usage.
long	executeInsert(java.lang.String table, SupportSQLiteStatement statement) Execute statement and return the ID of the row inserted due to this call.
int	executeUpdateDelete(java.util.Set<java.lang.String> tables, SupportSQLiteStatement statement) See executeUpdateDelete(String, SupportSQLiteStatement) for usage.
int	executeUpdateDelete(java.lang.String table, SupportSQLiteStatement statement) Execute statement, if the the number of rows affected by execution of this SQL statement is of any importance to the caller - for example, UPDATE / DELETE SQL statements.
SupportSQLiteDatabase	getReadableDatabase() Create and/or open a database.
SupportSQLiteDatabase	getWritableDatabase() Create and/or open a database that will be used for reading and writing.
long	insert(java.lang.String table, int conflictAlgorithm, android.content.ContentValues values) Insert a row into the specified table and notify any subscribed queries.
BriteDatabase.Transaction	newNonExclusiveTransaction() Begins a transaction in IMMEDIATE mode for this thread.
BriteDatabase.Transaction	newTransaction() Begin a transaction for this thread.
android.database.Cursor	query(java.lang.String sql, java.lang.Object... args) Runs the provided SQL and returns a Cursor over the result set.
void	setLoggingEnabled(boolean enabled) Control whether debug logging is enabled.
int	update(java.lang.String table, int conflictAlgorithm, android.content.ContentValues values, java.lang.String whereClause, java.lang.String... whereArgs) Update rows in the specified table and notify any subscribed queries.

Methods inherited from class java.lang.Object

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

Method Detail

setLoggingEnabled

public void setLoggingEnabled(boolean enabled)

Control whether debug logging is enabled.

getReadableDatabase

public SupportSQLiteDatabase getReadableDatabase()

Create and/or open a database. This will be the same object returned by SupportSQLiteOpenHelper#getWritableDatabase unless some problem, such as a full disk, requires the database to be opened read-only. In that case, a read-only database object will be returned. If the problem is fixed, a future call to SupportSQLiteOpenHelper#getWritableDatabase may succeed, in which case the read-only database object will be closed and the read/write object will be returned in the future.

Like SupportSQLiteOpenHelper#getWritableDatabase, this method may take a long time to return, so you should not call it from the application main thread, including from ContentProvider.onCreate().

Returns:

a database object valid until SupportSQLiteOpenHelper#getWritableDatabase or close() is called.

Throws:

android.database.sqlite.SQLiteException - if the database cannot be opened

getWritableDatabase

public SupportSQLiteDatabase getWritableDatabase()

Create and/or open a database that will be used for reading and writing. The first time this is called, the database will be opened and Callback#onCreate, Callback#onUpgrade and/or Callback#onOpen will be called.

Once opened successfully, the database is cached, so you can call this method every time you need to write to the database. (Make sure to call close() when you no longer need the database.) Errors such as bad permissions or a full disk may cause this method to fail, but future attempts may succeed if the problem is fixed.

Database upgrade may take a long time, you should not call this method from the application main thread, including from ContentProvider.onCreate().

Returns:

a read/write database object valid until close() is called

Throws:

android.database.sqlite.SQLiteException - if the database cannot be opened for writing

newTransaction

public BriteDatabase.Transaction newTransaction()

Begin a transaction for this thread.

Transactions may nest. If the transaction is not in progress, then a database connection is obtained and a new transaction is started. Otherwise, a nested transaction is started.

Each call to newTransaction must be matched exactly by a call to BriteDatabase.Transaction.end(). To mark a transaction as successful, call BriteDatabase.Transaction.markSuccessful() before calling BriteDatabase.Transaction.end(). If the transaction is not successful, or if any of its nested transactions were not successful, then the entire transaction will be rolled back when the outermost transaction is ended.

Transactions queue up all query notifications until they have been applied.

Here is the standard idiom for transactions:

 try (Transaction transaction = db.newTransaction()) {
   ...
   transaction.markSuccessful();
 }
 

Manually call BriteDatabase.Transaction.end() when try-with-resources is not available:

 Transaction transaction = db.newTransaction();
 try {
   ...
   transaction.markSuccessful();
 } finally {
   transaction.end();
 }
 

See Also:

SupportSQLiteDatabase#beginTransaction()

newNonExclusiveTransaction

public BriteDatabase.Transaction newNonExclusiveTransaction()

Begins a transaction in IMMEDIATE mode for this thread.

Transactions may nest. If the transaction is not in progress, then a database connection is obtained and a new transaction is started. Otherwise, a nested transaction is started.

Each call to newNonExclusiveTransaction must be matched exactly by a call to BriteDatabase.Transaction.end(). To mark a transaction as successful, call BriteDatabase.Transaction.markSuccessful() before calling BriteDatabase.Transaction.end(). If the transaction is not successful, or if any of its nested transactions were not successful, then the entire transaction will be rolled back when the outermost transaction is ended.

Transactions queue up all query notifications until they have been applied.

Here is the standard idiom for transactions:

 try (Transaction transaction = db.newNonExclusiveTransaction()) {
   ...
   transaction.markSuccessful();
 }
 

Manually call BriteDatabase.Transaction.end() when try-with-resources is not available:

 Transaction transaction = db.newNonExclusiveTransaction();
 try {
   ...
   transaction.markSuccessful();
 } finally {
   transaction.end();
 }
 

See Also:

SupportSQLiteDatabase#beginTransactionNonExclusive()

close

public void close()

Close the underlying SupportSQLiteOpenHelper and remove cached readable and writeable databases. This does not prevent existing observables from retaining existing references as well as attempting to create new ones for new subscriptions.

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

createQuery

public QueryObservable createQuery(java.lang.String table,
                                   java.lang.String sql,
                                   java.lang.Object... args)

Create an observable which will notify subscribers with a query for execution. Subscribers are responsible for always closing Cursor instance returned from the SqlBrite.Query.

Subscribers will receive an immediate notification for initial data as well as subsequent notifications for when the supplied table's data changes through the insert, update, and delete methods of this class. Unsubscribe when you no longer want updates to a query.

Since database triggers are inherently asynchronous, items emitted from the returned observable use the Scheduler supplied to SqlBrite.wrapDatabaseHelper(SupportSQLiteOpenHelper, Scheduler). For consistency, the immediate notification sent on subscribe also uses this scheduler. As such, calling subscribeOn on the returned observable has no effect.

Note: To skip the immediate notification and only receive subsequent notifications when data has changed call skip(1) on the returned observable.

Warning: this method does not perform the query! Only by subscribing to the returned Observable will the operation occur.

See Also:

SupportSQLiteDatabase#query(String, Object[])

createQuery

public QueryObservable createQuery(java.lang.Iterable<java.lang.String> tables,
                                   java.lang.String sql,
                                   java.lang.Object... args)

See createQuery(String, String, Object...) for usage. This overload allows for monitoring multiple tables for changes.

See Also:

SupportSQLiteDatabase#query(String, Object[])

createQuery

public QueryObservable createQuery(java.lang.String table,
                                   SupportSQLiteQuery query)

Create an observable which will notify subscribers with a query for execution. Subscribers are responsible for always closing Cursor instance returned from the SqlBrite.Query.

Subscribers will receive an immediate notification for initial data as well as subsequent notifications for when the supplied table's data changes through the insert, update, and delete methods of this class. Unsubscribe when you no longer want updates to a query.

Since database triggers are inherently asynchronous, items emitted from the returned observable use the Scheduler supplied to SqlBrite.wrapDatabaseHelper(SupportSQLiteOpenHelper, Scheduler). For consistency, the immediate notification sent on subscribe also uses this scheduler. As such, calling subscribeOn on the returned observable has no effect.

Note: To skip the immediate notification and only receive subsequent notifications when data has changed call skip(1) on the returned observable.

Warning: this method does not perform the query! Only by subscribing to the returned Observable will the operation occur.

See Also:

SupportSQLiteDatabase#query(SupportSQLiteQuery)

createQuery

public QueryObservable createQuery(java.lang.Iterable<java.lang.String> tables,
                                   SupportSQLiteQuery query)

See createQuery(String, SupportSQLiteQuery) for usage. This overload allows for monitoring multiple tables for changes.

See Also:

SupportSQLiteDatabase#query(SupportSQLiteQuery)

query

public android.database.Cursor query(java.lang.String sql,
                                     java.lang.Object... args)

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

See Also:

SupportSQLiteDatabase#query(String, Object[])

insert

public long insert(java.lang.String table,
                   int conflictAlgorithm,
                   android.content.ContentValues values)

Insert a row into the specified table and notify any subscribed queries.

See Also:

SupportSQLiteDatabase#insert(String, int, ContentValues)

delete

public int delete(java.lang.String table,
                  java.lang.String whereClause,
                  java.lang.String... whereArgs)

Delete rows from the specified table and notify any subscribed queries. This method will not trigger a notification if no rows were deleted.

See Also:

SupportSQLiteDatabase#delete(String, String, Object[])

update

public int update(java.lang.String table,
                  int conflictAlgorithm,
                  android.content.ContentValues values,
                  java.lang.String whereClause,
                  java.lang.String... whereArgs)

Update rows in the specified table and notify any subscribed queries. This method will not trigger a notification if no rows were updated.

See Also:

SupportSQLiteDatabase#update(String, int, ContentValues, String, Object[])

execute

public void execute(java.lang.String sql)

Execute sql provided it is NOT a SELECT or any other SQL statement that returns data. No data can be returned (such as the number of affected rows). Instead, use insert(java.lang.String, int, android.content.ContentValues), update(java.lang.String, int, android.content.ContentValues, java.lang.String, java.lang.String...), et al, when possible.

No notifications will be sent to queries if sql affects the data of a table.

See Also:

SupportSQLiteDatabase#execSQL(String)

execute

public void execute(java.lang.String sql,
                    java.lang.Object... args)

Execute sql provided it is NOT a SELECT or any other SQL statement that returns data. No data can be returned (such as the number of affected rows). Instead, use insert(java.lang.String, int, android.content.ContentValues), update(java.lang.String, int, android.content.ContentValues, java.lang.String, java.lang.String...), et al, when possible.

No notifications will be sent to queries if sql affects the data of a table.

See Also:

SupportSQLiteDatabase#execSQL(String, Object[])

executeAndTrigger

public void executeAndTrigger(java.lang.String table,
                              java.lang.String sql)

Execute sql provided it is NOT a SELECT or any other SQL statement that returns data. No data can be returned (such as the number of affected rows). Instead, use insert(java.lang.String, int, android.content.ContentValues), update(java.lang.String, int, android.content.ContentValues, java.lang.String, java.lang.String...), et al, when possible.

A notification to queries for table will be sent after the statement is executed.

See Also:

SupportSQLiteDatabase#execSQL(String)

executeAndTrigger

public void executeAndTrigger(java.util.Set<java.lang.String> tables,
                              java.lang.String sql)

See executeAndTrigger(String, String) for usage. This overload allows for triggering multiple tables.

See Also:

executeAndTrigger(String, String)

executeAndTrigger

public void executeAndTrigger(java.lang.String table,
                              java.lang.String sql,
                              java.lang.Object... args)

Execute sql provided it is NOT a SELECT or any other SQL statement that returns data. No data can be returned (such as the number of affected rows). Instead, use insert(java.lang.String, int, android.content.ContentValues), update(java.lang.String, int, android.content.ContentValues, java.lang.String, java.lang.String...), et al, when possible.

A notification to queries for table will be sent after the statement is executed.

See Also:

SupportSQLiteDatabase#execSQL(String, Object[])

executeAndTrigger

public void executeAndTrigger(java.util.Set<java.lang.String> tables,
                              java.lang.String sql,
                              java.lang.Object... args)

See executeAndTrigger(String, String, Object...) for usage. This overload allows for triggering multiple tables.

See Also:

executeAndTrigger(String, String, Object...)

executeUpdateDelete

public int executeUpdateDelete(java.lang.String table,
                               SupportSQLiteStatement statement)

Execute statement, if the the number of rows affected by execution of this SQL statement is of any importance to the caller - for example, UPDATE / DELETE SQL statements.

Returns:

the number of rows affected by this SQL statement execution.

Throws:

android.database.SQLException - If the SQL string is invalid

See Also:

SupportSQLiteStatement#executeUpdateDelete()

executeUpdateDelete

public int executeUpdateDelete(java.util.Set<java.lang.String> tables,
                               SupportSQLiteStatement statement)

See executeUpdateDelete(String, SupportSQLiteStatement) for usage. This overload allows for triggering multiple tables.

See Also:

executeUpdateDelete(String, SupportSQLiteStatement)

executeInsert

public long executeInsert(java.lang.String table,
                          SupportSQLiteStatement statement)

Execute statement and return the ID of the row inserted due to this call. The SQL statement should be an INSERT for this to be a useful call.

Returns:

the row ID of the last row inserted, if this insert is successful. -1 otherwise.

Throws:

android.database.SQLException - If the SQL string is invalid

See Also:

SupportSQLiteStatement#executeInsert()

executeInsert

public long executeInsert(java.util.Set<java.lang.String> tables,
                          SupportSQLiteStatement statement)

See executeInsert(String, SupportSQLiteStatement) for usage. This overload allows for triggering multiple tables.

See Also:

executeInsert(String, SupportSQLiteStatement)