com.couchbase.lite.internal.database.sqlite

Class SQLiteConnectionPool

java.lang.Object

com.couchbase.lite.internal.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

Modifier and Type	Method and Description
SQLiteConnection	acquireConnection(java.lang.String sql, int connectionFlags, 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(Printer printer, boolean verbose) Dumps debugging information about this connection pool.
protected void	finalize()
static SQLiteConnectionPool	open(SQLiteDatabaseConfiguration configuration, SQLiteConnectionListener connectionListener) 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,
                                        SQLiteConnectionListener connectionListener)

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,
                                          CancellationSignal cancellationSignal)

Acquires a connection from the pool.

The caller must call releaseConnection(com.couchbase.lite.internal.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.

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.

dump

public void dump(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