Class ThreadSafeDatabase

java.lang.Object

com.codename1.db.Database

com.codename1.db.ThreadSafeDatabase

public class ThreadSafeDatabase
extends Database

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.

Field Summary

Fields inherited from class Database

inTransaction

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method	Description
void	beginTransaction()	Starts a transaction.
void	changeKey(DatabaseConfig config)	Changes the key of this open database, or removes it entirely.
void	close()	Closes the database
void	commitTransaction()	Commits current transaction
void	execute(String sql)	Execute an update query.
void	execute(String sql, Object... params)	Execute an update query with params.
void	execute(String sql, String[] params)	Execute an update query with params.
Cursor	executeQuery(String sql)	This method should be called with SELECT type statements that return row set.
Cursor	executeQuery(String sql, Object... params)	This method should be called with SELECT type statements that return row set it accepts object with params.
Cursor	executeQuery(String sql, String[] params)	This method should be called with SELECT type statements that return row set.
EasyThread	getThread()	Returns the underlying easy thread we can use to pipe tasks to the db thread
boolean	isInTransaction()	Reports whether a transaction is currently open on this database.
void	rollbackTransaction()	Rolls back current transaction

Methods inherited from class Database

abandonFailedCommit, beforeFirst, checkBeginTransaction, checkEndTransaction, coerceToText, count, decrypt, delete, encrypt, exists, forgetManagedKey, getDatabasePath, isBlobQueryParameterSupported, isCustomPathSupported, isEncrypted, isEncryptionSupported, isLegacyBehavior, markTransactionEnded, openOrCreate, openOrCreate, setLegacyBehavior, supportsWasNull, toPragmaLiteral, wasNull

Methods inherited from class Object

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

Constructor Details

ThreadSafeDatabase

public ThreadSafeDatabase(Database db)

Wraps the given database with a threadsafe version

Parameters

• db: 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

Description copied from class: Database

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

Specified by:

beginTransaction in class Database

Throws:

IOException

commitTransaction

public void commitTransaction()
                       throws IOException

Description copied from class: Database

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

Specified by:

commitTransaction in class Database

Throws:

IOException

rollbackTransaction

public void rollbackTransaction()
                         throws IOException

Description copied from class: Database

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

Specified by:

rollbackTransaction in class Database

Throws:

IOException

isInTransaction

public boolean isInTransaction()

Description copied from class: Database

Reports whether a transaction is currently open on this database.

Returns

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

Overrides:

isInTransaction in class Database

changeKey

public void changeKey(DatabaseConfig config)
               throws IOException

Description copied from class: Database

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: the new key, or DatabaseConfig#plain() to decrypt

Throws

• IOException: if the key cannot be changed

Overrides:

changeKey in class Database

Throws:

IOException

close

public void close()

Description copied from class: Database

Closes the database

Throws

• IOException

Specified by:

close in class Database

execute

public void execute(String sql)
             throws IOException

Description copied from class: Database

Execute an update query. Used for INSERT, UPDATE, DELETE and similar sql statements.

Parameters

• sql: the sql to execute

Throws

• IOException

Specified by:

execute in class Database

Throws:

IOException

execute

public void execute(String sql,
 String[] params)
             throws IOException

Description copied from class: Database

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: the sql to execute

• params: to bind to the query where the '?' exists

Throws

• IOException

Specified by:

execute in class Database

Throws:

IOException

executeQuery

public Cursor executeQuery(String sql,
 String[] params)
                    throws IOException

Description copied from class: Database

This method should be called with SELECT type statements that return row set.

Parameters

• sql: the sql to execute

• params: to bind to the query where the '?' exists

Returns

a cursor to iterate over the results

Throws

• IOException

Specified by:

executeQuery in class Database

Throws:

IOException

executeQuery

public Cursor executeQuery(String sql)
                    throws IOException

Description copied from class: Database

This method should be called with SELECT type statements that return row set.

Parameters

• sql: the sql to execute

Returns

a cursor to iterate over the results

Throws

• IOException

Specified by:

executeQuery in class Database

Throws:

IOException

executeQuery

public Cursor executeQuery(String sql,
 Object... params)
                    throws IOException

Description copied from class: Database

This method should be called with SELECT type statements that return row set it accepts object with params.

Parameters

• sql: the sql to execute

• params: @param params 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

Overrides:

executeQuery in class Database

Throws:

IOException

execute

public void execute(String sql,
 Object... params)
             throws IOException

Description copied from class: Database

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: the sql to execute

• params: @param params to bind to the query where the '?' exists, supported object types are String, byte[], Double, Long and null

Throws

• IOException

Overrides:

execute in class Database

Throws:

IOException