Package net.zetetic.database.sqlcipher

Class SQLiteConnectionPool

  • All Implemented Interfaces:
    java.io.Closeable , java.lang.AutoCloseable 
    
public final class SQLiteConnectionPool
 implements 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).

    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.

    • Constructor Detail

    • Method Detail

      • close

         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.

      • reconfigure

         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.

      • acquireConnection

         SQLiteConnection acquireConnection(String sql, int connectionFlags, CancellationSignal cancellationSignal)

        Acquires a connection from the pool.

        The caller must call releaseConnection 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.

      • releaseConnection

         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.

      • shouldYieldConnection

         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.

      • dump

         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.