com.squareup.sqlbrite

Class BriteDatabase

java.lang.Object

com.squareup.sqlbrite.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 SQLiteOpenHelper 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.ConflictAlgorithm
static interface	BriteDatabase.Transaction An in-progress database transaction.

Method Summary

Modifier and Type	Method and Description
void	close() Close the underlying SQLiteOpenHelper and remove cached readable and writeable databases.
QueryObservable	createQuery(java.lang.Iterable<java.lang.String> tables, java.lang.String sql, java.lang.String... args) See createQuery(String, String, String...) for usage.
QueryObservable	createQuery(java.lang.String table, java.lang.String sql, java.lang.String... args) 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.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	insert(java.lang.String table, android.content.ContentValues values) Insert a row into the specified table and notify any subscribed queries.
long	insert(java.lang.String table, android.content.ContentValues values, int conflictAlgorithm) Insert a row into the specified table and notify any subscribed queries.
BriteDatabase.Transaction	newTransaction() Begin a transaction for this thread.
android.database.Cursor	query(java.lang.String sql, java.lang.String... 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, android.content.ContentValues values, int conflictAlgorithm, java.lang.String whereClause, java.lang.String... whereArgs) Update rows in the specified table and notify any subscribed queries.
int	update(java.lang.String table, 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.

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:

SQLiteDatabase.beginTransaction()

close

public void close()

Close the underlying SQLiteOpenHelper 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.String... 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(android.database.sqlite.SQLiteOpenHelper, 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:

SQLiteDatabase.rawQuery(String, String[])

createQuery

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

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

See Also:

SQLiteDatabase.rawQuery(String, String[])

query

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

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

See Also:

SQLiteDatabase.rawQuery(String, String[])

insert

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

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

See Also:

SQLiteDatabase.insert(String, String, ContentValues)

insert

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

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

See Also:

SQLiteDatabase.insertWithOnConflict(String, String, ContentValues, int)

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:

SQLiteDatabase.delete(String, String, String[])

update

public int update(java.lang.String table,
                  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:

SQLiteDatabase.update(String, ContentValues, String, String[])

update

public int update(java.lang.String table,
                  android.content.ContentValues values,
                  int conflictAlgorithm,
                  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:

SQLiteDatabase.updateWithOnConflict(String, ContentValues, String, String[], int)

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, android.content.ContentValues), update(java.lang.String, 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:

SQLiteDatabase.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, android.content.ContentValues), update(java.lang.String, 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:

SQLiteDatabase.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, android.content.ContentValues), update(java.lang.String, 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:

SQLiteDatabase.execSQL(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, android.content.ContentValues), update(java.lang.String, 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:

SQLiteDatabase.execSQL(String, Object[])