SQLiteRawStatement

public final class SQLiteRawStatement
extends Object implements Closeable

java.lang.Object
   ↳ android.database.sqlite.SQLiteRawStatement

A SQLiteRawStatement represents a SQLite prepared statement. The methods correspond very closely to SQLite APIs that operate on a sqlite_stmt object. In general, each API in this class corresponds to a single SQLite API.

A SQLiteRawStatement must be created through a database, and there must be a transaction open at the time. Statements are implicitly closed when the outermost transaction ends, or if the current transaction is marked successful. Statements may be explicitly closed at any time with close(). The close() operation is idempotent and may be called multiple times without harm.

Multiple SQLiteRawStatements may be open simultaneously. They are independent of each other. Closing one statement does not affect any other statement nor does it have any effect on the enclosing transaction.

Once a SQLiteRawStatement has been closed, no further database operations are permitted on that statement. An IllegalStateException will be thrown if a database operation is attempted on a closed statement.

All operations on a SQLiteRawStatement must be invoked from the thread that created it. A IllegalStateException will be thrown if cross-thread use is detected.

A common pattern for statements is try-with-resources. 

 // Begin a transaction.
 database.beginTransaction();
 try (SQLiteRawStatement statement = database.createRawStatement("SELECT * FROM ...")) {
     while (statement.step()) {
         // Fetch columns from the result rows.
     }
     database.setTransactionSuccessful();
 } finally {
     database.endTransaction();
 }
Note that SQLiteRawStatement is unrelated to SQLiteStatement.

See also:

Summary

Constants

int SQLITE_DATA_TYPE_BLOB

The constant returned by getColumnType(int) when the column value is SQLITE_BLOB.

int SQLITE_DATA_TYPE_FLOAT

The constant returned by getColumnType(int) when the column value is SQLITE_FLOAT.

int SQLITE_DATA_TYPE_INTEGER

The constant returned by getColumnType(int) when the column value is SQLITE_INTEGER.

int SQLITE_DATA_TYPE_NULL

The constant returned by getColumnType(int) when the column value is SQLITE_NULL.

int SQLITE_DATA_TYPE_TEXT

The constant returned by getColumnType(int) when the column value is SQLITE_TEXT.

Public methods

void bindBlob(int parameterIndex, byte[] value)

Bind a blob to a parameter.

void bindBlob(int parameterIndex, byte[] value, int offset, int length)

Bind a blob to a parameter.

void bindDouble(int parameterIndex, double value)

Bind a double to a parameter.

void bindInt(int parameterIndex, int value)

Bind an int to a parameter.

void bindLong(int parameterIndex, long value)

Bind a long to the parameter.

void bindNull(int parameterIndex)

Bind a null to the parameter.

void bindText(int parameterIndex, String value)

Bind a string to the parameter.

void clearBindings()

Clear all parameter bindings.

void close()

Close the object and release any native resources.

byte[] getColumnBlob(int columnIndex)

Return the column value of the result row as a blob.

double getColumnDouble(int columnIndex)

Return the column value as a double.

int getColumnInt(int columnIndex)

Return the column value as a int.

int getColumnLength(int columnIndex)

Return the length of the column value in the result row.

long getColumnLong(int columnIndex)

Return the column value as a long.

String getColumnName(int columnIndex)

Return the name of the column in the result row.

String getColumnText(int columnIndex)

Return the column value as a text.

int getColumnType(int columnIndex)

Return the type of the column in the result row.

int getParameterCount()

Return the number of parameters in the statement.

int getParameterIndex(String name)

Return the index of the parameter with specified name.

String getParameterName(int parameterIndex)

Return the name of the parameter at the specified index.

int getResultColumnCount()

Return the number of columns in the current result row.

boolean isOpen()

Return true if the statement is still open and false otherwise.

int readColumnBlob(int columnIndex, byte[] buffer, int offset, int length, int srcOffset)

Copy the column value of the result row, interpreted as a blob, into the buffer.

void reset()

Reset the statement.

boolean step()

Step to the next result row.

String toString()

Returns a string representation of the object.

Inherited methods

Constants

SQLITE_DATA_TYPE_BLOB

Added in API level 35 
public static final int SQLITE_DATA_TYPE_BLOB

The constant returned by getColumnType(int) when the column value is SQLITE_BLOB.

Constant Value: 4 (0x00000004)

SQLITE_DATA_TYPE_FLOAT

Added in API level 35 
public static final int SQLITE_DATA_TYPE_FLOAT

The constant returned by getColumnType(int) when the column value is SQLITE_FLOAT.

Constant Value: 2 (0x00000002)

SQLITE_DATA_TYPE_INTEGER

Added in API level 35 
public static final int SQLITE_DATA_TYPE_INTEGER

The constant returned by getColumnType(int) when the column value is SQLITE_INTEGER.

Constant Value: 1 (0x00000001)

SQLITE_DATA_TYPE_NULL

Added in API level 35 
public static final int SQLITE_DATA_TYPE_NULL

The constant returned by getColumnType(int) when the column value is SQLITE_NULL.

Constant Value: 5 (0x00000005)

SQLITE_DATA_TYPE_TEXT

Added in API level 35 
public static final int SQLITE_DATA_TYPE_TEXT

The constant returned by getColumnType(int) when the column value is SQLITE_TEXT.

Constant Value: 3 (0x00000003)

Public methods

bindBlob

Added in API level 35 
public void bindBlob (int parameterIndex, 
                byte[] value)

Bind a blob to a parameter. Parameter indices start at 1. The function throws if the parameter index is out of bounds.

Parameters
parameterIndex int: The index of the parameter in the query. It is one-based.
value byte: The value to be bound to the parameter. This value cannot be null.
Throws
IllegalStateException if the statement is closed or this is a foreign thread.
SQLiteBindOrColumnIndexOutOfRangeException if the parameter is out of range.
SQLiteException if a native error occurs.

See also:

bindBlob

Added in API level 35 
public void bindBlob (int parameterIndex, 
                byte[] value, 
                int offset, 
                int length)

Bind a blob to a parameter. Parameter indices start at 1. The function throws if the parameter index is out of bounds. The sub-array value[offset] to value[offset+length-1] is bound.

Parameters
parameterIndex int: The index of the parameter in the query. It is one-based.
value byte: The value to be bound to the parameter. This value cannot be null.
offset int: An offset into the value array
length int: The number of bytes to bind from the value array.
Throws
IllegalStateException if the statement is closed or this is a foreign thread.
IllegalArgumentException if the sub-array exceeds the bounds of the value array.
SQLiteBindOrColumnIndexOutOfRangeException if the parameter is out of range.
SQLiteException if a native error occurs.

See also:

bindDouble

Added in API level 35 
public void bindDouble (int parameterIndex, 
                double value)

Bind a double to a parameter. Parameter indices start at 1. The function throws if the parameter index is out of bounds.

Parameters
parameterIndex int: The index of the parameter in the query. It is one-based.
value double: The value to be bound to the parameter.
Throws
IllegalStateException if the statement is closed or this is a foreign thread.
SQLiteBindOrColumnIndexOutOfRangeException if the parameter is out of range.
SQLiteException if a native error occurs.

bindInt

Added in API level 35 
public void bindInt (int parameterIndex, 
                int value)

Bind an int to a parameter. Parameter indices start at 1. The function throws if the parameter index is out of bounds.

Parameters
parameterIndex int: The index of the parameter in the query. It is one-based.
value int

Throws
IllegalStateException if the statement is closed or this is a foreign thread.
SQLiteBindOrColumnIndexOutOfRangeException if the parameter is out of range.
SQLiteException if a native error occurs.

See also:

bindLong

Added in API level 35 
public void bindLong (int parameterIndex, 
                long value)

Bind a long to the parameter. Parameter indices start at 1. The function throws if the parameter index is out of bounds.

Parameters
parameterIndex int

value long: The value to be bound to the parameter.
Throws
IllegalStateException if the statement is closed or this is a foreign thread.
SQLiteBindOrColumnIndexOutOfRangeException if the parameter is out of range.
SQLiteException if a native error occurs.

See also:

bindNull

Added in API level 35 
public void bindNull (int parameterIndex)

Bind a null to the parameter. Parameter indices start at 1. The function throws if the parameter index is out of bounds.

Parameters
parameterIndex int: The index of the parameter in the query. It is one-based.
Throws
IllegalStateException if the statement is closed or this is a foreign thread.
SQLiteBindOrColumnIndexOutOfRangeException if the parameter is out of range.
SQLiteException if a native error occurs.

See also:

bindText

Added in API level 35 
public void bindText (int parameterIndex, 
                String value)

Bind a string to the parameter. Parameter indices start at 1. The function throws if the parameter index is out of bounds. The string may not be null.

Parameters
parameterIndex int: The index of the parameter in the query. It is one-based.
value String: The value to be bound to the parameter. This value cannot be null.
Throws
IllegalStateException if the statement is closed or this is a foreign thread.
SQLiteBindOrColumnIndexOutOfRangeException if the parameter is out of range.
SQLiteException if a native error occurs.

clearBindings

Added in API level 35 
public void clearBindings ()

Clear all parameter bindings.

Throws
IllegalStateException if the statement is closed or this is a foreign thread.
SQLiteException if a native error occurs.

close

Added in API level 35 
public void close ()

Close the object and release any native resources. It is not an error to call this on an already-closed object.

getColumnBlob

Added in API level 35 
public byte[] getColumnBlob (int columnIndex)

Return the column value of the result row as a blob. Column indices start at 0. This throws an exception if column is not in the result. This returns null if the column value is null. The column value will be converted if it is not of type SQLITE_DATA_TYPE_BLOB; see the sqlite documentation for details.

Parameters
columnIndex int: The index of a column in the result row. It is zero-based.
Returns
byte[] The value of the column as a blob, or null if the column is NULL.
Throws
IllegalStateException if the statement is closed or this is a foreign thread.
SQLiteBindOrColumnIndexOutOfRangeException if the column is out of range.
SQLiteException if a native error occurs.

getColumnDouble

Added in API level 35 
public double getColumnDouble (int columnIndex)

Return the column value as a double. Column indices start at 0. This throws an exception if column is not in the result. The column value will be converted if it is not of type SQLITE_DATA_TYPE_FLOAT; see the sqlite documentation for details.

Parameters
columnIndex int: The index of a column in the result row. It is zero-based.
Returns
double The value of a column as a double.
Throws
IllegalStateException if the statement is closed or this is a foreign thread.
SQLiteBindOrColumnIndexOutOfRangeException if the column is out of range.
SQLiteException if a native error occurs.

getColumnInt

Added in API level 35 
public int getColumnInt (int columnIndex)

Return the column value as a int. Column indices start at 0. This throws an exception if column is not in the result. The column value will be converted if it is not of type SQLITE_DATA_TYPE_INTEGER; see the sqlite documentation for details.

Parameters
columnIndex int: The index of a column in the result row. It is zero-based.
Returns
int The value of the column as an int.
Throws
IllegalStateException if the statement is closed or this is a foreign thread.
SQLiteBindOrColumnIndexOutOfRangeException if the column is out of range.
SQLiteException if a native error occurs.

See also:

getColumnLength

Added in API level 35 
public int getColumnLength (int columnIndex)

Return the length of the column value in the result row. Column indices start at 0. This returns 0 for a null and number of bytes for text or blob. Numeric values are converted to a string and the length of the string is returned. See the sqlite documentation for details. Note that this cannot be used to distinguish a null value from an empty text or blob. Note that this returns the number of bytes in the text value, not the number of characters.

Parameters
columnIndex int: The index of a column in the result row. It is zero-based.
Returns
int The length, in bytes, of the value in the column.
Throws
IllegalStateException if the statement is closed or this is a foreign thread.
SQLiteBindOrColumnIndexOutOfRangeException if the column is out of range.
SQLiteException if a native error occurs.

getColumnLong

Added in API level 35 
public long getColumnLong (int columnIndex)

Return the column value as a long. Column indices start at 0. This throws an exception if column is not in the result. The column value will be converted if it is not of type SQLITE_DATA_TYPE_INTEGER; see the sqlite documentation for details.

Parameters
columnIndex int: The index of a column in the result row. It is zero-based.
Returns
long The value of the column as an long.
Throws
IllegalStateException if the statement is closed or this is a foreign thread.
SQLiteBindOrColumnIndexOutOfRangeException if the column is out of range.
SQLiteException if a native error occurs.

getColumnName

Added in API level 35 
public String getColumnName (int columnIndex)

Return the name of the column in the result row. Column indices start at 0. This throws an exception if column is not in the result.

Parameters
columnIndex int: The index of a column in the result row. It is zero-based.
Returns
String The name of the column in the result row. This value cannot be null.
Throws
IllegalStateException if the statement is closed or this is a foreign thread.
SQLiteBindOrColumnIndexOutOfRangeException if the column is out of range.
SQLiteOutOfMemoryException if the database cannot allocate memory for the name.

getColumnText

Added in API level 35 
public String getColumnText (int columnIndex)

Return the column value as a text. Column indices start at 0. This throws an exception if column is not in the result. The column value will be converted if it is not of type SQLITE_DATA_TYPE_TEXT; see the sqlite documentation for details.

Parameters
columnIndex int: The index of a column in the result row. It is zero-based.
Returns
String The value of the column as a string. This value cannot be null.
Throws
IllegalStateException if the statement is closed or this is a foreign thread.
SQLiteBindOrColumnIndexOutOfRangeException if the column is out of range.
SQLiteException if a native error occurs.

getColumnType

Added in API level 35 
public int getColumnType (int columnIndex)

Return the type of the column in the result row. Column indices start at 0.

Parameters
columnIndex int: The index of a column in the result row. It is zero-based.
Returns
int The type of the value in the column of the result row. Value is SQLITE_DATA_TYPE_INTEGER, SQLITE_DATA_TYPE_FLOAT, SQLITE_DATA_TYPE_TEXT, SQLITE_DATA_TYPE_BLOB, or SQLITE_DATA_TYPE_NULL
Throws
IllegalStateException if the statement is closed or this is a foreign thread.
SQLiteBindOrColumnIndexOutOfRangeException if the column is out of range.
SQLiteException if a native error occurs.

getParameterCount

Added in API level 35 
public int getParameterCount ()

Return the number of parameters in the statement.

Returns
int The number of parameters in the statement.
Throws
IllegalStateException if the statement is closed or this is a foreign thread.

getParameterIndex

Added in API level 35 
public int getParameterIndex (String name)

Return the index of the parameter with specified name. If the name does not match any parameter, 0 is returned.

Parameters
name String: The name of a parameter. This value cannot be null.
Returns
int The index of the parameter or 0 if the name does not identify a parameter.
Throws
IllegalStateException if the statement is closed or this is a foreign thread.

getParameterName

Added in API level 35 
public String getParameterName (int parameterIndex)

Return the name of the parameter at the specified index. Null is returned if there is no such parameter or if the parameter does not have a name.

Parameters
parameterIndex int: The index of the parameter.
Returns
String The name of the parameter. This value may be null.
Throws
IllegalStateException if the statement is closed or this is a foreign thread.

getResultColumnCount

Added in API level 35 
public int getResultColumnCount ()

Return the number of columns in the current result row.

Returns
int The number of columns in the result row.
Throws
IllegalStateException if the statement is closed or this is a foreign thread.

isOpen

Added in API level 35 
public boolean isOpen ()

Return true if the statement is still open and false otherwise.

Returns
boolean True if the statement is open.

readColumnBlob

Added in API level 35 
public int readColumnBlob (int columnIndex, 
                byte[] buffer, 
                int offset, 
                int length, 
                int srcOffset)

Copy the column value of the result row, interpreted as a blob, into the buffer. Column indices start at 0. This throws an exception if column is not in the result row. Bytes are copied into the buffer starting at the offset. Bytes are copied from the blob starting at srcOffset. Length bytes are copied unless the column value has fewer bytes available. The function returns the number of bytes copied. The column value will be converted if it is not of type SQLITE_DATA_TYPE_BLOB; see the sqlite documentation for details.

Parameters
columnIndex int: The index of a column in the result row. It is zero-based.
buffer byte: A pre-allocated array to be filled with the value of the column. This value cannot be null.
offset int: An offset into the buffer: copying starts here.
length int: The number of bytes to copy.
srcOffset int: The offset into the blob from which to start copying.
Returns
int the number of bytes that were copied.
Throws
IllegalStateException if the statement is closed or this is a foreign thread.
IllegalArgumentException if the buffer is too small for offset+length.
SQLiteBindOrColumnIndexOutOfRangeException if the column is out of range.
SQLiteException if a native error occurs.

reset

Added in API level 35 
public void reset ()

Reset the statement.

Throws
IllegalStateException if the statement is closed or this is a foreign thread.
SQLiteException if a native error occurs.

See also:

step

Added in API level 35 
public boolean step ()

Step to the next result row. This returns true if the statement stepped to a new row, and false if the statement is done. The method throws on any other result, including a busy or locked database. If WAL is enabled then the database should never be locked or busy.

Returns
boolean True if a row is available and false otherwise.
Throws
IllegalStateException if the statement is closed or this is a foreign thread.
SQLiteDatabaseLockedException if the database is locked or busy.
SQLiteException if a native error occurs.

See also:

toString

Added in API level 35 
public String toString ()

Returns a string representation of the object.

Returns
String a string representation of the object.