public final class SQLiteConnectionPool extends Object implements Closeable
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.
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.
|
Modifier and Type | Method and Description |
---|---|
SQLiteConnection |
acquireConnection(String sql,
int connectionFlags,
CancellationSignal cancellationSignal)
Acquires a connection from the pool.
|
void |
close()
Closes the connection pool.
|
void |
collectDbStats(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()
Called by the garbage collector on an object when garbage collection
determines that there are no more references to the object.
|
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.
|
String |
toString()
Returns a string representation of the object.
|
public static final int CONNECTION_FLAG_READ_ONLY
This flag indicates that the connection will only be used to perform read-only operations.
public static final int 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.
public static final int CONNECTION_FLAG_INTERACTIVE
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.
protected void finalize() throws Throwable
Object
finalize
method to dispose of
system resources or to perform other cleanup.
The general contract of finalize
is that it is invoked
if and when the JavaTM virtual
machine has determined that there is no longer any
means by which this object can be accessed by any thread that has
not yet died, except as a result of an action taken by the
finalization of some other object or class which is ready to be
finalized. The finalize
method may take any action, including
making this object available again to other threads; the usual purpose
of finalize
, however, is to perform cleanup actions before
the object is irrevocably discarded. For example, the finalize method
for an object that represents an input/output connection might perform
explicit I/O transactions to break the connection before the object is
permanently discarded.
The finalize
method of class Object
performs no
special action; it simply returns normally. Subclasses of
Object
may override this definition.
The Java programming language does not guarantee which thread will
invoke the finalize
method for any given object. It is
guaranteed, however, that the thread that invokes finalize will not
be holding any user-visible synchronization locks when finalize is
invoked. If an uncaught exception is thrown by the finalize method,
the exception is ignored and finalization of that object terminates.
After the finalize
method has been invoked for an object, no
further action is taken until the Java virtual machine has again
determined that there is no longer any means by which this object can
be accessed by any thread that has not yet died, including possible
actions by other objects or classes which are ready to be finalized,
at which point the object may be discarded.
The finalize
method is never invoked more than once by a Java
virtual machine for any given object.
Any exception thrown by the finalize
method causes
the finalization of this object to be halted, but is otherwise
ignored.
public static SQLiteConnectionPool open(SQLiteDatabaseConfiguration configuration)
configuration
- The database configuration.SQLiteException
- if a database error occurs.public void close()
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.
close
in interface Closeable
close
in interface AutoCloseable
IllegalStateException
- if the pool has been closed.public void reconfigure(SQLiteDatabaseConfiguration configuration)
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.
configuration
- The new configuration.IllegalStateException
- if the pool has been closed.public SQLiteConnection acquireConnection(String sql, int connectionFlags, CancellationSignal cancellationSignal)
The caller must call releaseConnection(android.database.sqlite.SQLiteConnection)
to release the connection
back to the pool when it is finished. Failure to do so will result
in much unpleasantness.
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.IllegalStateException
- if the pool has been closed.SQLiteException
- if a database error occurs.OperationCanceledException
- if the operation was canceled.public void releaseConnection(SQLiteConnection connection)
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.
connection
- The connection to release. Must not be null.IllegalStateException
- if the connection was not acquired
from this pool or if it has already been released.public boolean shouldYieldConnection(SQLiteConnection connection, int connectionFlags)
connection
- The connection owned by the session.connectionFlags
- The connection request flags.IllegalStateException
- if the connection was not acquired
from this pool or if it has already been released.public void collectDbStats(ArrayList<SQLiteDebug.DbStats> dbStatsList)
dbStatsList
- The list to populate.public void dump(Printer printer, boolean verbose)
printer
- The printer to receive the dump, not null.verbose
- True to dump more verbose information.public String toString()
Object
toString
method returns a string that
"textually represents" this object. The result should
be a concise but informative representation that is easy for a
person to read.
It is recommended that all subclasses override this method.
The toString
method for class Object
returns a string consisting of the name of the class of which the
object is an instance, the at-sign character `@
', and
the unsigned hexadecimal representation of the hash code of the
object. In other words, this method returns a string equal to the
value of:
getClass().getName() + '@' + Integer.toHexString(hashCode())