# 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 on the worker, and shuts the worker down.
  `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, beginTransactionMode, checkBeginTransaction, checkEndTransaction, checkNoTransactionForKeyChange, coerceToText, count, decrypt, delete, encrypt, exists, forgetManagedKey, getDatabasePath, hasAttachments, isBlobQueryParameterSupported, isCustomPathSupported, isDatabaseBeingDeleted, isEncrypted, isEncryptionSupported, isLegacyBehavior, markTransactionEnded, normalizeDatabaseKey, normalizeDatabasePathKey, noteConnectionClosed, noteEngineTransactionState, noteFirstStatementTransactionControl, noteScriptTransactionControl, openDatabaseCount, openOrCreate, openOrCreate, registerOpenDatabase, releaseKeyChangeClaim, releaseOpenDatabase, requireAttachmentsHeld, requireQueryStatement, requireSoleConnectionForKeyChange, reserveAttachments, reserveAttachments, setLegacyBehavior, supportsNestedTransactions, supportsWasNull, toPragmaLiteral, transactionControlKeyword, 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() 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.

    Specified by:
      `close` in class `Database`
    Throws:
      `IOException`

  - ### 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`