com.couchbase.lite.internal.database.sqlite

Class SQLiteConnection

java.lang.Object

com.couchbase.lite.internal.database.sqlite.SQLiteConnection

All Implemented Interfaces:

CancellationSignal.OnCancelListener

public final class SQLiteConnection
extends java.lang.Object
implements CancellationSignal.OnCancelListener

Represents a SQLite database connection. Each connection wraps an instance of a native sqlite3 object.

When database connection pooling is enabled, there can be multiple active connections to the same database. Otherwise there is typically only one connection per database.

When the SQLite WAL feature is enabled, multiple readers and one writer can concurrently access the database. Without WAL, readers and writers are mutually exclusive.

Ownership and concurrency guarantees

Connection objects are not thread-safe. They are acquired as needed to perform a database operation and are then returned to the pool. At any given time, a connection is either owned and used by a SQLiteSession object or the SQLiteConnectionPool. Those classes are responsible for serializing operations to guard against concurrent use of a connection.

The guarantee of having a single owner allows this class to be implemented without locks and greatly simplifies resource management.

Encapsulation guarantees

The connection object object owns *all* of the SQLite related native objects that are associated with the connection. What's more, there are no other objects in the system that are capable of obtaining handles to those native objects. Consequently, when the connection is closed, we do not have to worry about what other components might have references to its associated SQLite state -- there are none.

Encapsulation is what ensures that the connection object's lifecycle does not become a tortured mess of finalizers and reference queues.

Reentrance

This class must tolerate reentrant execution of SQLite operations because triggers may call custom SQLite functions that perform additional queries.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	SQLiteConnection.PreparedStatement Holder type for a prepared statement.

Method Summary

Modifier and Type	Method and Description
void	dump(Printer printer, boolean verbose) Dumps debugging information about this connection.
void	execute(java.lang.String sql, java.lang.Object[] bindArgs, CancellationSignal cancellationSignal) Executes a statement that does not return a result.
int	executeForChangedRowCount(java.lang.String sql, java.lang.Object[] bindArgs, CancellationSignal cancellationSignal) Executes a statement that returns a count of the number of rows that were changed.
long	executeForLastInsertedRowId(java.lang.String sql, java.lang.Object[] bindArgs, CancellationSignal cancellationSignal) Executes a statement that returns the row id of the last row inserted by the statement.
long	executeForLong(java.lang.String sql, java.lang.Object[] bindArgs, CancellationSignal cancellationSignal) Executes a statement that returns a single long result.
java.lang.String	executeForString(java.lang.String sql, java.lang.Object[] bindArgs, CancellationSignal cancellationSignal) Executes a statement that returns a single String result.
SQLiteConnection.PreparedStatement	executePrepareStatementNoRelease(java.lang.String sql, java.lang.Object[] bindArgs)
void	executeReleasePrepareStatement(SQLiteConnection.PreparedStatement statement)
protected void	finalize()
long	getConnectionHandle() Gets SQLite native connection handler.
int	getConnectionId() Gets the unique id of this connection.
java.util.Locale	getLocale() Get current locale of the connection
boolean	isPrimaryConnection() Returns true if this is the primary database connection.
void	onCancel() Called when CancellationSignal.cancel() is invoked.
void	prepare(java.lang.String sql, SQLiteStatementInfo outStatementInfo) Prepares a statement for execution but does not bind its parameters or execute it.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

finalize

protected void finalize()
                 throws java.lang.Throwable

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable

getConnectionId

public int getConnectionId()

Gets the unique id of this connection.

Returns:

The connection id.

isPrimaryConnection

public boolean isPrimaryConnection()

Returns true if this is the primary database connection.

Returns:

True if this is the primary database connection.

getConnectionHandle

public long getConnectionHandle()

Gets SQLite native connection handler.

Returns:

The connection handler

getLocale

public java.util.Locale getLocale()

Get current locale of the connection

Returns:

prepare

public void prepare(java.lang.String sql,
                    SQLiteStatementInfo outStatementInfo)

Prepares a statement for execution but does not bind its parameters or execute it.

This method can be used to check for syntax errors during compilation prior to execution of the statement. If the outStatementInfo argument is not null, the provided SQLiteStatementInfo object is populated with information about the statement.

A prepared statement makes no reference to the arguments that may eventually be bound to it, consequently it it possible to cache certain prepared statements such as SELECT or INSERT/UPDATE statements. If the statement is cacheable, then it will be stored in the cache for later.

To take advantage of this behavior as an optimization, the connection pool provides a method to acquire a connection that already has a given SQL statement in its prepared statement cache so that it is ready for execution.

Parameters:

sql - The SQL statement to prepare.

outStatementInfo - The SQLiteStatementInfo object to populate with information about the statement, or null if none.

Throws:

SQLiteException - if an error occurs, such as a syntax error.

execute

public void execute(java.lang.String sql,
                    java.lang.Object[] bindArgs,
                    CancellationSignal cancellationSignal)

Executes a statement that does not return a result.

Parameters:

sql - The SQL statement to execute.

bindArgs - The arguments to bind, or null if none.

cancellationSignal - A signal to cancel the operation in progress, or null if none.

Throws:

SQLiteException - if an error occurs, such as a syntax error or invalid number of bind arguments.

OperationCanceledException - if the operation was canceled.

executeForLong

public long executeForLong(java.lang.String sql,
                           java.lang.Object[] bindArgs,
                           CancellationSignal cancellationSignal)

Executes a statement that returns a single long result.

Parameters:

sql - The SQL statement to execute.

bindArgs - The arguments to bind, or null if none.

cancellationSignal - A signal to cancel the operation in progress, or null if none.

Returns:

The value of the first column in the first row of the result set as a long, or zero if none.

Throws:

SQLiteException - if an error occurs, such as a syntax error or invalid number of bind arguments.

OperationCanceledException - if the operation was canceled.

executeForString

public java.lang.String executeForString(java.lang.String sql,
                                         java.lang.Object[] bindArgs,
                                         CancellationSignal cancellationSignal)

Executes a statement that returns a single String result.

Parameters:

sql - The SQL statement to execute.

bindArgs - The arguments to bind, or null if none.

cancellationSignal - A signal to cancel the operation in progress, or null if none.

Returns:

The value of the first column in the first row of the result set as a String, or null if none.

Throws:

SQLiteException - if an error occurs, such as a syntax error or invalid number of bind arguments.

OperationCanceledException - if the operation was canceled.

executeForChangedRowCount

public int executeForChangedRowCount(java.lang.String sql,
                                     java.lang.Object[] bindArgs,
                                     CancellationSignal cancellationSignal)

Executes a statement that returns a count of the number of rows that were changed. Use for UPDATE or DELETE SQL statements.

Parameters:

sql - The SQL statement to execute.

bindArgs - The arguments to bind, or null if none.

cancellationSignal - A signal to cancel the operation in progress, or null if none.

Returns:

The number of rows that were changed.

Throws:

SQLiteException - if an error occurs, such as a syntax error or invalid number of bind arguments.

OperationCanceledException - if the operation was canceled.

executeForLastInsertedRowId

public long executeForLastInsertedRowId(java.lang.String sql,
                                        java.lang.Object[] bindArgs,
                                        CancellationSignal cancellationSignal)

Executes a statement that returns the row id of the last row inserted by the statement. Use for INSERT SQL statements.

Parameters:

sql - The SQL statement to execute.

bindArgs - The arguments to bind, or null if none.

cancellationSignal - A signal to cancel the operation in progress, or null if none.

Returns:

The row id of the last row that was inserted, or 0 if none.

Throws:

SQLiteException - if an error occurs, such as a syntax error or invalid number of bind arguments.

OperationCanceledException - if the operation was canceled.

executePrepareStatementNoRelease

public SQLiteConnection.PreparedStatement executePrepareStatementNoRelease(java.lang.String sql,
                                                                           java.lang.Object[] bindArgs)

executeReleasePrepareStatement

public void executeReleasePrepareStatement(SQLiteConnection.PreparedStatement statement)

onCancel

public void onCancel()

Description copied from interface: CancellationSignal.OnCancelListener

Called when CancellationSignal.cancel() is invoked.

Specified by:

onCancel in interface CancellationSignal.OnCancelListener

dump

public void dump(Printer printer,
                 boolean verbose)

Dumps debugging information about this connection.

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