SQLiteConnectionPool (sqlite-android 0.10.0 API)

java.lang.Object
- org.sqlite.database.sqlite.SQLiteConnectionPool

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable
```
public final class SQLiteConnectionPool
extends java.lang.Object
implements java.io.Closeable
```
Maintains a pool of active SQLite database connections.
At any given time, a connection is either owned by the pool, or it has been acquired by a SQLiteSession. When the SQLiteSession is finished with the connection it is using, it must return the connection back to the pool.
The pool holds strong references to the connections it owns. However, it only holds weak references to the connections that sessions have acquired from it. Using weak references in the latter case ensures that the connection pool can detect when connections have been improperly abandoned so that it can create new connections to replace them if needed.
The connection pool is thread-safe (but the connections themselves are not).

Exception safety

This code attempts to maintain the invariant that opened connections are always owned. Unfortunately that means it needs to handle exceptions all over to ensure that broken connections get cleaned up. Most operations invokving SQLite can throw SQLiteException or other runtime exceptions. This is a bit of a pain to deal with because the compiler cannot help us catch missing exception handling code.
The general rule for this file: If we are making calls out to SQLiteConnection then we must be prepared to handle any runtime exceptions it might throw at us. Note that out-of-memory is an Error, not a RuntimeException. We don't trouble ourselves handling out of memory because it is hard to do anything at all sensible then and most likely the VM is about to crash.

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`CONNECTION_FLAG_INTERACTIVE` Connection flag: Connection is being used interactively.
`static int`	`CONNECTION_FLAG_PRIMARY_CONNECTION_AFFINITY` Connection flag: Primary connection affinity.
`static int`	`CONNECTION_FLAG_READ_ONLY` Connection flag: Read-only.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`SQLiteConnection`	`acquireConnection(java.lang.String sql, int connectionFlags, android.os.CancellationSignal cancellationSignal)` Acquires a connection from the pool.
`void`	`close()` Closes the connection pool.
`void`	`collectDbStats(java.util.ArrayList<SQLiteDebug.DbStats> dbStatsList)` Collects statistics about database connection memory usage.
`void`	`dump(android.util.Printer printer, boolean verbose)` Dumps debugging information about this connection pool.
`void`	`enableLocalizedCollators()`
`protected void`	`finalize()`
`static SQLiteConnectionPool`	`open(SQLiteDatabaseConfiguration configuration)` Opens a connection pool for the specified database.
`void`	`reconfigure(SQLiteDatabaseConfiguration configuration)` Reconfigures the database configuration of the connection pool and all of its connections.
`void`	`releaseConnection(SQLiteConnection connection)` Releases a connection back to the pool.
`boolean`	`shouldYieldConnection(SQLiteConnection connection, int connectionFlags)` Returns true if the session should yield the connection due to contention over available database connections.
`java.lang.String`	`toString()`

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - CONNECTION_FLAG_READ_ONLY
```
public static final int CONNECTION_FLAG_READ_ONLY
```
    Connection flag: Read-only.
    This flag indicates that the connection will only be used to perform read-only operations.
    
    See Also:
    
    Constant Field Values
  - CONNECTION_FLAG_PRIMARY_CONNECTION_AFFINITY
```
public static final int CONNECTION_FLAG_PRIMARY_CONNECTION_AFFINITY
```
    Connection flag: Primary connection affinity.
    This flag indicates that the primary connection is required. This flag helps support legacy applications that expect most data modifying operations to be serialized by locking the primary database connection. Setting this flag essentially implements the old "db lock" concept by preventing an operation from being performed until it can obtain exclusive access to the primary connection.
    
    See Also:
    
    Constant Field Values
  - CONNECTION_FLAG_INTERACTIVE
```
public static final int CONNECTION_FLAG_INTERACTIVE
```
    Connection flag: Connection is being used interactively.
    This flag indicates that the connection is needed by the UI thread. The connection pool can use this flag to elevate the priority of the database connection request.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - finalize
```
protected void finalize()
                 throws java.lang.Throwable
```
    Overrides:
    
    finalize in class java.lang.Object
    
    Throws:
    
    java.lang.Throwable
  - open
```
public static SQLiteConnectionPool open(SQLiteDatabaseConfiguration configuration)
```
    Opens a connection pool for the specified database.
    
    Parameters:
    
    configuration - The database configuration.
    
    Returns:
    
    The connection pool.
    
    Throws:
    
    SQLiteException - if a database error occurs.
  - close
```
public void close()
```
    Closes the connection pool.
    When the connection pool is closed, it will refuse all further requests to acquire connections. All connections that are currently available in the pool are closed immediately. Any connections that are still in use will be closed as soon as they are returned to the pool.
    
    Specified by:
    
    close in interface java.io.Closeable
    
    Specified by:
    
    close in interface java.lang.AutoCloseable
    
    Throws:
    
    java.lang.IllegalStateException - if the pool has been closed.
  - reconfigure
```
public void reconfigure(SQLiteDatabaseConfiguration configuration)
```
    Reconfigures the database configuration of the connection pool and all of its connections.
    Configuration changes are propagated down to connections immediately if they are available or as soon as they are released. This includes changes that affect the size of the pool.
    
    Parameters:
    
    configuration - The new configuration.
    
    Throws:
    
    java.lang.IllegalStateException - if the pool has been closed.
  - acquireConnection
```
public SQLiteConnection acquireConnection(java.lang.String sql,
                                          int connectionFlags,
                                          android.os.CancellationSignal cancellationSignal)
```
    Acquires a connection from the pool.
    The caller must call releaseConnection(org.sqlite.database.sqlite.SQLiteConnection) to release the connection back to the pool when it is finished. Failure to do so will result in much unpleasantness.
    
    Parameters:
    
    sql - If not null, try to find a connection that already has the specified SQL statement in its prepared statement cache.
    
    connectionFlags - The connection request flags.
    
    cancellationSignal - A signal to cancel the operation in progress, or null if none.
    
    Returns:
    
    The connection that was acquired, never null.
    
    Throws:
    
    java.lang.IllegalStateException - if the pool has been closed.
    
    SQLiteException - if a database error occurs.
    
    android.os.OperationCanceledException - if the operation was canceled.
  - releaseConnection
```
public void releaseConnection(SQLiteConnection connection)
```
    Releases a connection back to the pool.
    It is ok to call this method after the pool has closed, to release connections that were still in use at the time of closure.
    
    Parameters:
    
    connection - The connection to release. Must not be null.
    
    Throws:
    
    java.lang.IllegalStateException - if the connection was not acquired from this pool or if it has already been released.
  - shouldYieldConnection
```
public boolean shouldYieldConnection(SQLiteConnection connection,
                                     int connectionFlags)
```
    Returns true if the session should yield the connection due to contention over available database connections.
    
    Parameters:
    
    connection - The connection owned by the session.
    
    connectionFlags - The connection request flags.
    
    Returns:
    
    True if the session should yield its connection.
    
    Throws:
    
    java.lang.IllegalStateException - if the connection was not acquired from this pool or if it has already been released.
  - collectDbStats
```
public void collectDbStats(java.util.ArrayList<SQLiteDebug.DbStats> dbStatsList)
```
    Collects statistics about database connection memory usage.
    
    Parameters:
    
    dbStatsList - The list to populate.
  - enableLocalizedCollators
```
public void enableLocalizedCollators()
```
  - dump
```
public void dump(android.util.Printer printer,
                 boolean verbose)
```
    Dumps debugging information about this connection pool.
    
    Parameters:
    
    printer - The printer to receive the dump, not null.
    
    verbose - True to dump more verbose information.
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object

Class SQLiteConnectionPool

Exception safety

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

CONNECTION_FLAG_READ_ONLY

CONNECTION_FLAG_PRIMARY_CONNECTION_AFFINITY

CONNECTION_FLAG_INTERACTIVE

Method Detail

finalize

open

close

reconfigure

acquireConnection

releaseConnection

shouldYieldConnection

collectDbStats

enableLocalizedCollators

dump

toString