public class ThreadSafeDatabase

  1. Object
  2. Database
  3. ThreadSafeDatabase

Confines a database and its cursors to a single thread.

A Database is not thread safe, and neither are the cursors it hands out. Wrapping one in this class routes every call through one worker thread, so several application threads can share a connection without coordinating.

Database db = new ThreadSafeDatabase(Database.openOrCreate("shared.db"));

The cost is that every call is a thread handoff, so a tight loop over a large result set is meaningfully slower than using a connection per thread. Prefer one database per thread when the threads do not actually need to share state.

This class used to be deprecated, on the grounds that platform specific behaviour had defeated it. That behaviour has since been fixed: the iOS port no longer closes SQLite handles from the garbage collector thread, and it opens each connection in serialised mode rather than trying to configure the whole process.

Constructors

public ThreadSafeDatabase(Database db)Wraps the given database with a threadsafe version

Methods

public EasyThread getThread()Returns the underlying easy thread we can use to pipe tasks to the db thread
public void beginTransaction() throws IOExceptionStarts a transaction.
public void commitTransaction() throws IOExceptionCommits current transaction
public void rollbackTransaction() throws IOExceptionRolls back current transaction
public boolean isInTransaction()Reports whether a transaction is currently open on this database.
public void changeKey(DatabaseConfig config) throws IOExceptionChanges the key of this open database, or removes it entirely.
public void close() throws IOExceptionCloses the database on the worker, and shuts the worker down.
public void execute(String sql) throws IOExceptionExecute an update query.
public void execute(String sql, String[] params) throws IOExceptionExecute an update query with params.
public Cursor executeQuery(String sql, String[] params) throws IOExceptionThis method should be called with SELECT type statements that return row set.
public Cursor executeQuery(String sql) throws IOExceptionThis method should be called with SELECT type statements that return row set.
public Cursor executeQuery(String sql, Object... params) throws IOExceptionThis method should be called with SELECT type statements that return row set it accepts object with params.
public void execute(String sql, Object... params) throws IOExceptionExecute an update query with params.

Inherited fields

From Database

inTransaction

Inherited methods

From Database

isCustomPathSupported, isLegacyBehavior, setLegacyBehavior, openOrCreate, exists, delete, isDatabaseBeingDeleted, openDatabaseCount, getDatabasePath, openOrCreate, isEncryptionSupported, isEncrypted, encrypt, decrypt, forgetManagedKey, beforeFirst, count, isBlobQueryParameterSupported, wasNull, supportsWasNull, toPragmaLiteral, noteScriptTransactionControl, hasAttachments, reserveAttachments, reserveAttachments, requireAttachmentsHeld, noteConnectionClosed, noteFirstStatementTransactionControl, noteEngineTransactionState, transactionControlKeyword, beginTransactionMode, requireQueryStatement, normalizeDatabaseKey, normalizeDatabasePathKey, registerOpenDatabase, releaseOpenDatabase, requireSoleConnectionForKeyChange, releaseKeyChangeClaim, checkNoTransactionForKeyChange, supportsNestedTransactions, checkBeginTransaction, checkEndTransaction, markTransactionEnded, abandonFailedCommit, coerceToText

From Object

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

Constructor details

ThreadSafeDatabase

public ThreadSafeDatabase(Database db)
Wraps the given database with a threadsafe version

Parameters

db Database
the database

Method details

getThread

public EasyThread getThread()
Returns the underlying easy thread we can use to pipe tasks to the db thread

Returns

the easy thread object

beginTransaction

public void beginTransaction() throws IOException

Starts a transaction.

Transactions are flat. Calling this while a transaction is already open throws, and committing or rolling back returns the connection to autocommit. Closing a database with an open transaction rolls it back.

Throws

IOException
if the database is not open, or a transaction is already in progress

commitTransaction

public void commitTransaction() throws IOException

Commits current transaction

NOTE: Not supported in Javascript port. This method will do nothing when running in Javascript.

Throws

IOException
if database is not opened or transaction was not started

rollbackTransaction

public void rollbackTransaction() throws IOException

Rolls back current transaction

NOTE: Not supported in Javascript port. This method will do nothing when running in Javascript.

Throws

IOException
if database is not opened or transaction was not started

isInTransaction

public boolean isInTransaction()
Reports whether a transaction is currently open on this database.

Returns

true between a successful #beginTransaction() and its commit or rollback

changeKey

public void changeKey(DatabaseConfig config) throws IOException

Changes the key of this open database, or removes it entirely.

Passing a plaintext config decrypts the database. The engine performs the conversion as a single transaction and preserves schema metadata such as PRAGMA user_version.

Ports that support encryption override this. The default implementation reports that the platform cannot do it; it is deliberately concrete rather than abstract, because Database is public and is subclassed outside this repository.

Parameters

config DatabaseConfig
the new key, or DatabaseConfig#plain() to decrypt

Throws

IOException
if the key cannot be changed

close

public void close() throws IOException

Closes the database on the worker, and shuts the worker down.

Idempotent, and synchronous: it returns with the database closed, so a delete() on the next line does not race it. If the worker was stopped from outside – getThread() is public, and both kill() and killWhenIdle() on it are calls anybody can make – this waits for the work that worker had already accepted before closing the database itself, rather than closing it underneath an operation that is still running.

Throws

IOException

execute

public void execute(String sql) throws IOException
Execute an update query. Used for INSERT, UPDATE, DELETE and similar sql statements.

Parameters

sql String
the sql to execute

Throws

IOException

execute

public void execute(String sql, String[] params) throws IOException
Execute an update query with params. Used for INSERT, UPDATE, DELETE and similar sql statements. The sql can be constructed with ‘?’ and the params will be binded to the query

Parameters

sql String
the sql to execute
params String[]
to bind to the query where the ‘?’ exists

Throws

IOException

executeQuery

public Cursor executeQuery(String sql, String[] params) throws IOException
This method should be called with SELECT type statements that return row set.

Parameters

sql String
the sql to execute
params String[]
to bind to the query where the ‘?’ exists

Returns

a cursor to iterate over the results

Throws

IOException

executeQuery

public Cursor executeQuery(String sql) throws IOException
This method should be called with SELECT type statements that return row set.

Parameters

sql String
the sql to execute

Returns

a cursor to iterate over the results

Throws

IOException

executeQuery

public Cursor executeQuery(String sql, Object... params) throws IOException
This method should be called with SELECT type statements that return row set it accepts object with params.

Parameters

sql String
the sql to execute
params Object...
to bind to the query where the ‘?’ exists, supported object types are String, byte[], Double, Long and null

Returns

a cursor to iterate over the results

Throws

IOException

execute

public void execute(String sql, Object... params) throws IOException
Execute an update query with params. Used for INSERT, UPDATE, DELETE and similar sql statements. The sql can be constructed with ‘?’ and the params will be binded to the query

Parameters

sql String
the sql to execute
params Object...
to bind to the query where the ‘?’ exists, supported object types are String, byte[], Double, Long and null

Throws

IOException