Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Make new SQLite APIs public

Browse Source 
Bug: 279043253

Expose the new SQLite APIs as public APIs.

CTS tests are provided in a separate CL.

Test: atest
 * FrameworksCoreTests:android.database.sqlite

Change-Id: I4c3e803d51aa87a17735ce3b5e9c1e5d38e66253
This commit is contained in:
Lee Shombert
2023-06-27 14:53:01 -07:00
parent 24008f68a4
commit 2db4e949e6
4 changed files with 284 additions and 149 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
core/api/current.txt
View File

@@ -14271,6 +14271,7 @@ package android.database.sqlite {
method public android.database.sqlite.SQLiteStatement compileStatement(String) throws android.database.SQLException;
method @NonNull public static android.database.sqlite.SQLiteDatabase create(@Nullable android.database.sqlite.SQLiteDatabase.CursorFactory);
method @NonNull public static android.database.sqlite.SQLiteDatabase createInMemory(@NonNull android.database.sqlite.SQLiteDatabase.OpenParams);
method @NonNull public android.database.sqlite.SQLiteRawStatement createRawStatement(@NonNull String);
method public int delete(String, String, String[]);
method public static boolean deleteDatabase(@NonNull java.io.File);
method public void disableWriteAheadLogging();
@@ -14281,6 +14282,7 @@ package android.database.sqlite {
method public void execSQL(String, Object[]) throws android.database.SQLException;
method public static String findEditTable(String);
method public java.util.List<android.util.Pair<java.lang.String,java.lang.String>> getAttachedDbs();
method public long getLastInsertRowId();
method public long getMaximumSize();
method public long getPageSize();
method public String getPath();
@@ -14506,6 +14508,39 @@ package android.database.sqlite {
method public int update(@NonNull android.database.sqlite.SQLiteDatabase, @NonNull android.content.ContentValues, @Nullable String, @Nullable String[]);
}
public final class SQLiteRawStatement implements java.io.Closeable {
method public void bindBlob(int, @NonNull byte[]) throws android.database.sqlite.SQLiteException;
method public void bindBlob(int, @NonNull byte[], int, int) throws android.database.sqlite.SQLiteException;
method public void bindDouble(int, double) throws android.database.sqlite.SQLiteException;
method public void bindInt(int, int) throws android.database.sqlite.SQLiteException;
method public void bindLong(int, long) throws android.database.sqlite.SQLiteException;
method public void bindNull(int) throws android.database.sqlite.SQLiteException;
method public void bindText(int, @NonNull String) throws android.database.sqlite.SQLiteException;
method public void clearBindings();
method public void close();
method @Nullable public byte[] getColumnBlob(int) throws android.database.sqlite.SQLiteException;
method public double getColumnDouble(int) throws android.database.sqlite.SQLiteException;
method public int getColumnInt(int) throws android.database.sqlite.SQLiteException;
method public int getColumnLength(int) throws android.database.sqlite.SQLiteException;
method public long getColumnLong(int) throws android.database.sqlite.SQLiteException;
method @NonNull public String getColumnName(int) throws android.database.sqlite.SQLiteException;
method @NonNull public String getColumnText(int) throws android.database.sqlite.SQLiteException;
method public int getColumnType(int) throws android.database.sqlite.SQLiteException;
method public int getParameterCount();
method public int getParameterIndex(@NonNull String);
method @Nullable public String getParameterName(int);
method public int getResultColumnCount();
method public boolean isOpen();
method public int readColumnBlob(int, @NonNull byte[], int, int, int) throws android.database.sqlite.SQLiteException;
method public void reset();
method public boolean step() throws android.database.sqlite.SQLiteException;
field public static final int SQLITE_DATA_TYPE_BLOB = 4; // 0x4
field public static final int SQLITE_DATA_TYPE_FLOAT = 2; // 0x2
field public static final int SQLITE_DATA_TYPE_INTEGER = 1; // 0x1
field public static final int SQLITE_DATA_TYPE_NULL = 5; // 0x5
field public static final int SQLITE_DATA_TYPE_TEXT = 3; // 0x3
}
public class SQLiteReadOnlyDatabaseException extends android.database.sqlite.SQLiteException {
ctor public SQLiteReadOnlyDatabaseException();
ctor public SQLiteReadOnlyDatabaseException(String);

19
core/java/android/database/sqlite/SQLiteDatabase.java
View File

@@ -2171,11 +2171,11 @@ public final class SQLiteDatabase extends SQLiteClosable {
* Return a {@link SQLiteRawStatement} connected to the database. A transaction must be in
* progress or an exception will be thrown. The resulting object will be closed automatically
* when the current transaction closes.
*
* @param sql The SQL string to be compiled into a prepared statement.
* @return A {@link SQLiteRawStatement} holding the compiled SQL.
* @throws IllegalStateException if a transaction is not in progress.
* @throws SQLiteException if the SQL cannot be compiled.
* @hide
*/
@NonNull
public SQLiteRawStatement createRawStatement(@NonNull String sql) {
@@ -2184,16 +2184,19 @@ public final class SQLiteDatabase extends SQLiteClosable {
}
/**
* Return the "rowid" of the last row to be inserted on the current connection. See the
* SQLite documentation for the specific details. This method must only be called when inside
* a transaction. {@link IllegalStateException} is thrown if the method is called outside a
* transaction. If the function is called before any inserts in the current transaction, the
* value returned will be from a previous transaction, which may be from a different thread.
* Return the "rowid" of the last row to be inserted on the current connection. This method must
* only be called when inside a transaction. {@link IllegalStateException} is thrown if the
* method is called outside a transaction. If the function is called before any inserts in the
* current transaction, the value returned will be from a previous transaction, which may be
* from a different thread. If no inserts have occurred on the current connection, the function
* returns 0. See the SQLite documentation for the specific details.
*
* @see <a href="https://sqlite.org/c3ref/last_insert_rowid.html">sqlite3_last_insert_rowid</a>
*
* @return The ROWID of the last row to be inserted under this connection.
* @throws IllegalStateException if there is no current transaction.
* @hide
*/
public long lastInsertRowId() {
public long getLastInsertRowId() {
return getThreadSession().lastInsertRowId();
}

309
core/java/android/database/sqlite/SQLiteRawStatement.java
View File

@@ -31,10 +31,10 @@ import java.lang.ref.Reference;
import java.util.Objects;
/**
* Represents a SQLite statement. The methods correspond very closely to SQLite APIs that operate
* on a sqlite_stmt object. See the SQLite API documentation for complete details. In general,
* the APIs in this class correspond to the SQLite APIs with the same name, except that snake-case
* is changed to camel-case.
* A {@link 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.
* <p>
* A {@link 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
@@ -66,8 +66,9 @@ import java.util.Objects;
* database.endTransaction();
* }
* </pre></code>
* Note that this class is unrelated to {@link SQLiteStatement}.
* @hide
* Note that {@link SQLiteRawStatement} is unrelated to {@link SQLiteStatement}.
*
* @see <a href="http://sqlite.org/c3ref/stmt.html">sqlite3_stmt</a>
*/
public final class SQLiteRawStatement implements Closeable {
@@ -114,24 +115,46 @@ public final class SQLiteRawStatement implements Closeable {
* @hide
*/
@Retention(RetentionPolicy.SOURCE)
@IntDef(value = {SQLITE_INTEGER, SQLITE_FLOAT, SQLITE_TEXT, SQLITE_BLOB, SQLITE_NULL})
@IntDef(value = {
SQLITE_DATA_TYPE_INTEGER,
SQLITE_DATA_TYPE_FLOAT,
SQLITE_DATA_TYPE_TEXT,
SQLITE_DATA_TYPE_BLOB,
SQLITE_DATA_TYPE_NULL})
public @interface SQLiteDataType {}
public static final int SQLITE_INTEGER = 1;
public static final int SQLITE_FLOAT = 2;
public static final int SQLITE_TEXT = 3;
public static final int SQLITE_BLOB = 4;
public static final int SQLITE_NULL = 5;
/**
* The constant returned by {@link #getColumnType} when the column value is SQLITE_INTEGER.
*/
public static final int SQLITE_DATA_TYPE_INTEGER = 1;
/**
* SQLite error codes that are used by this class. Refer to the sqlite documentation for
* other error codes.
* The constant returned by {@link #getColumnType} when the column value is SQLITE_FLOAT.
*/
public static final int SQLITE_OK = 0;
public static final int SQLITE_BUSY = 5;
public static final int SQLITE_LOCKED = 6;
public static final int SQLITE_ROW = 100;
public static final int SQLITE_DONE = 101;
public static final int SQLITE_DATA_TYPE_FLOAT = 2;
/**
* The constant returned by {@link #getColumnType} when the column value is SQLITE_TEXT.
*/
public static final int SQLITE_DATA_TYPE_TEXT = 3;
/**
* The constant returned by {@link #getColumnType} when the column value is SQLITE_BLOB.
*/
public static final int SQLITE_DATA_TYPE_BLOB = 4;
/**
* The constant returned by {@link #getColumnType} when the column value is SQLITE_NULL.
*/
public static final int SQLITE_DATA_TYPE_NULL = 5;
/**
* SQLite error codes that are used by this class.
*/
private static final int SQLITE_BUSY = 5;
private static final int SQLITE_LOCKED = 6;
private static final int SQLITE_ROW = 100;
private static final int SQLITE_DONE = 101;
/**
* Create the statement with empty bindings. The construtor will throw
@@ -201,6 +224,7 @@ public final class SQLiteRawStatement implements Closeable {
/**
* Return true if the statement is still open and false otherwise.
*
* @return True if the statement is open.
*/
public boolean isOpen() {
@@ -208,9 +232,12 @@ public final class SQLiteRawStatement implements Closeable {
}
/**
* Step to the next result. This returns true if the statement stepped to a new row, and
* 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.
*
* @see <a href="http://sqlite.org/c3ref/step.html">sqlite3_step</a>
*
* @return True if a row is available and false otherwise.
* @throws IllegalStateException if the statement is closed or this is a foreign thread.
* @throws SQLiteDatabaseLockedException if the database is locked or busy.
@@ -239,11 +266,14 @@ public final class SQLiteRawStatement implements Closeable {
}
/**
* Step to the next result. This returns the raw error code code from the native method. The
* Step to the next result. This returns the raw result code code from the native method. The
* expected values are SQLITE_ROW and SQLITE_DONE. For other return values, clients must
* decode the error and handle it themselves.
* decode the error and handle it themselves. http://sqlite.org/rescode.html for the current
* list of result codes.
*
* @return The native result code from the sqlite3_step() operation.
* @throws IllegalStateException if the statement is closed or this is a foreign thread.
* @hide
*/
public int stepNoThrow() {
throwIfInvalid();
@@ -255,8 +285,10 @@ public final class SQLiteRawStatement implements Closeable {
}
/**
* Reset the statement. The sqlite3 API returns an error code if the last call to step
* generated an error; this function discards those error codes.
* Reset the statement.
*
* @see <a href="http://sqlite.org/c3ref/reset.html">sqlite3_reset</a>
*
* @throws IllegalStateException if the statement is closed or this is a foreign thread.
* @throws SQLiteException if a native error occurs.
*/
@@ -271,6 +303,9 @@ public final class SQLiteRawStatement implements Closeable {
/**
* Clear all parameter bindings.
*
* @see <a href="http://sqlite.org/c3ref/clear_bindings.html">sqlite3_clear_bindings</a>
*
* @throws IllegalStateException if the statement is closed or this is a foreign thread.
* @throws SQLiteException if a native error occurs.
*/
@@ -285,10 +320,14 @@ public final class SQLiteRawStatement implements Closeable {
/**
* Return the number of parameters in the statement.
*
* @see
* <a href="http://sqlite.org/c3ref/bind_parameter_count.html">sqlite3_bind_parameter_count</a>
*
* @return The number of parameters in the statement.
* @throws IllegalStateException if the statement is closed or this is a foreign thread.
*/
public int bindParameterCount() {
public int getParameterCount() {
throwIfInvalid();
try {
return nativeBindParameterCount(mStatement);
@@ -300,11 +339,15 @@ public final class SQLiteRawStatement implements Closeable {
/**
* Return the index of the parameter with specified name. If the name does not match any
* parameter, 0 is returned.
*
* @see
* <a href="http://sqlite.org/c3ref/bind_parameter_index.html">sqlite3_bind_parameter_index</a>
*
* @param name The name of a parameter.
* @return 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.
*/
public int bindParameterIndex(@NonNull String name) {
public int getParameterIndex(@NonNull String name) {
Objects.requireNonNull(name);
throwIfInvalid();
try {
@@ -317,16 +360,19 @@ public final class SQLiteRawStatement implements Closeable {
/**
* 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.
* @param parameter The index of the parameter.
*
* @see
* <a href="http://sqlite.org/c3ref/bind_parameter_name.html">sqlite3_bind_parameter_name</a>
*
* @param parameterIndex The index of the parameter.
* @return The name of the parameter.
* @throws IllegalStateException if the statement is closed or this is a foreign thread.
* @throws SQLiteBindOrColumnIndexOutOfRangeException if the parameter is out of range.
*/
@Nullable
public String bindParameterName(int parameter) {
public String getParameterName(int parameterIndex) {
throwIfInvalid();
try {
return nativeBindParameterName(mStatement, parameter);
return nativeBindParameterName(mStatement, parameterIndex);
} finally {
Reference.reachabilityFence(this);
}
@@ -335,17 +381,20 @@ public final class SQLiteRawStatement implements Closeable {
/**
* Bind a blob to a parameter. Parameter indices start at 1. The function throws if the
* parameter index is out of bounds.
* @param parameter The index of the parameter in the query. It is one-based.
*
* @see <a href="http://sqlite.org/c3ref/bind_blob.html">sqlite3_bind_blob</a>
*
* @param parameterIndex The index of the parameter in the query. It is one-based.
* @param value The value to be bound to the parameter.
* @throws IllegalStateException if the statement is closed or this is a foreign thread.
* @throws SQLiteBindOrColumnIndexOutOfRangeException if the parameter is out of range.
* @throws SQLiteException if a native error occurs.
*/
public void bindBlob(int parameter, @NonNull byte[] value) throws SQLiteException {
public void bindBlob(int parameterIndex, @NonNull byte[] value) throws SQLiteException {
Objects.requireNonNull(value);
throwIfInvalid();
try {
nativeBindBlob(mStatement, parameter, value, 0, value.length);
nativeBindBlob(mStatement, parameterIndex, value, 0, value.length);
} finally {
Reference.reachabilityFence(this);
}
@@ -355,7 +404,10 @@ public final class SQLiteRawStatement implements Closeable {
* 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.
* @param parameter The index of the parameter in the query. It is one-based.
*
* @see <a href="http://sqlite.org/c3ref/bind_blob.html">sqlite3_bind_blob</a>
*
* @param parameterIndex The index of the parameter in the query. It is one-based.
* @param value The value to be bound to the parameter.
* @param offset An offset into the value array
* @param length The number of bytes to bind from the value array.
@@ -364,13 +416,13 @@ public final class SQLiteRawStatement implements Closeable {
* @throws SQLiteBindOrColumnIndexOutOfRangeException if the parameter is out of range.
* @throws SQLiteException if a native error occurs.
*/
public void bindBlob(int parameter, @NonNull byte[] value, int offset, int length)
public void bindBlob(int parameterIndex, @NonNull byte[] value, int offset, int length)
throws SQLiteException {
Objects.requireNonNull(value);
throwIfInvalid();
throwIfInvalidBounds(value.length, offset, length);
try {
nativeBindBlob(mStatement, parameter, value, offset, length);
nativeBindBlob(mStatement, parameterIndex, value, offset, length);
} finally {
Reference.reachabilityFence(this);
}
@@ -379,16 +431,19 @@ public final class SQLiteRawStatement implements Closeable {
/**
* Bind a double to a parameter. Parameter indices start at 1. The function throws if the
* parameter index is out of bounds.
* @param parameter The index of the parameter in the query. It is one-based.
*
* @see <a href="http://sqlite.org/c3ref/bind_blob.html">sqlite3_bind_double</a>
*
* @param parameterIndex The index of the parameter in the query. It is one-based.
* @param value The value to be bound to the parameter.
* @throws IllegalStateException if the statement is closed or this is a foreign thread.
* @throws SQLiteBindOrColumnIndexOutOfRangeException if the parameter is out of range.
* @throws SQLiteException if a native error occurs.
*/
public void bindDouble(int parameter, double value) throws SQLiteException {
public void bindDouble(int parameterIndex, double value) throws SQLiteException {
throwIfInvalid();
try {
nativeBindDouble(mStatement, parameter, value);
nativeBindDouble(mStatement, parameterIndex, value);
} finally {
Reference.reachabilityFence(this);
}
@@ -397,15 +452,18 @@ public final class SQLiteRawStatement implements Closeable {
/**
* Bind an int to a parameter. Parameter indices start at 1. The function throws if the
* parameter index is out of bounds.
* @param parameter The index of the parameter in the query. It is one-based.
*
* @see <a href="http://sqlite.org/c3ref/bind_blob.html">sqlite3_bind_int</a>
*
* @param parameterIndex 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.
* @throws SQLiteBindOrColumnIndexOutOfRangeException if the parameter is out of range.
* @throws SQLiteException if a native error occurs.
*/
public void bindInt(int parameter, int value) throws SQLiteException {
public void bindInt(int parameterIndex, int value) throws SQLiteException {
throwIfInvalid();
try {
nativeBindInt(mStatement, parameter, value);
nativeBindInt(mStatement, parameterIndex, value);
} finally {
Reference.reachabilityFence(this);
}
@@ -414,15 +472,18 @@ public final class SQLiteRawStatement implements Closeable {
/**
* Bind a long to the parameter. Parameter indices start at 1. The function throws if the
* parameter index is out of bounds.
*
* @see <a href="http://sqlite.org/c3ref/bind_blob.html">sqlite3_bind_int64</a>
*
* @param value The value to be bound to the parameter.
* @throws IllegalStateException if the statement is closed or this is a foreign thread.
* @throws SQLiteBindOrColumnIndexOutOfRangeException if the parameter is out of range.
* @throws SQLiteException if a native error occurs.
*/
public void bindLong(int parameter, long value) throws SQLiteException {
public void bindLong(int parameterIndex, long value) throws SQLiteException {
throwIfInvalid();
try {
nativeBindLong(mStatement, parameter, value);
nativeBindLong(mStatement, parameterIndex, value);
} finally {
Reference.reachabilityFence(this);
}
@@ -431,15 +492,18 @@ public final class SQLiteRawStatement implements Closeable {
/**
* Bind a null to the parameter. Parameter indices start at 1. The function throws if the
* parameter index is out of bounds.
* @param parameter The index of the parameter in the query. It is one-based.
*
* @see <a href="http://sqlite.org/c3ref/bind_blob.html">sqlite3_bind_null</a>
*
* @param parameterIndex 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.
* @throws SQLiteBindOrColumnIndexOutOfRangeException if the parameter is out of range.
* @throws SQLiteException if a native error occurs.
*/
public void bindNull(int parameter) throws SQLiteException {
public void bindNull(int parameterIndex) throws SQLiteException {
throwIfInvalid();
try {
nativeBindNull(mStatement, parameter);
nativeBindNull(mStatement, parameterIndex);
} finally {
Reference.reachabilityFence(this);
}
@@ -448,17 +512,20 @@ public final class SQLiteRawStatement implements Closeable {
/**
* 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.
* @param parameter The index of the parameter in the query. It is one-based.
*
* @see <a href="http://sqlite.org/c3ref/bind_blob.html">sqlite3_bind_text16</a>
*
* @param parameterIndex The index of the parameter in the query. It is one-based.
* @param value The value to be bound to the parameter.
* @throws IllegalStateException if the statement is closed or this is a foreign thread.
* @throws SQLiteBindOrColumnIndexOutOfRangeException if the parameter is out of range.
* @throws SQLiteException if a native error occurs.
*/
public void bindText(int parameter, @NonNull String value) throws SQLiteException {
public void bindText(int parameterIndex, @NonNull String value) throws SQLiteException {
Objects.requireNonNull(value);
throwIfInvalid();
try {
nativeBindText(mStatement, parameter, value);
nativeBindText(mStatement, parameterIndex, value);
} finally {
Reference.reachabilityFence(this);
}
@@ -466,10 +533,13 @@ public final class SQLiteRawStatement implements Closeable {
/**
* Return the number of columns in the current result row.
*
* @see <a href="http://sqlite.org/c3ref/column_count.html">sqlite3_column_count</a>
*
* @return The number of columns in the result row.
* @throws IllegalStateException if the statement is closed or this is a foreign thread.
*/
public int getResultColumnsCount() {
public int getResultColumnCount() {
throwIfInvalid();
try {
return nativeColumnCount(mStatement);
@@ -480,17 +550,20 @@ public final class SQLiteRawStatement implements Closeable {
/**
* Return the type of the column in the result row. Column indices start at 0.
* @param column The index of a column in the result row. It is zero-based.
*
* @see <a href="http://sqlite.org/c3ref/column_blob.html">sqlite3_column_type</a>
*
* @param columnIndex The index of a column in the result row. It is zero-based.
* @return The type of the value in the column of the result row.
* @throws IllegalStateException if the statement is closed or this is a foreign thread.
* @throws SQLiteBindOrColumnIndexOutOfRangeException if the column is out of range.
* @throws SQLiteException if a native error occurs.
*/
@SQLiteDataType
public int getType(int column) throws SQLiteException {
public int getColumnType(int columnIndex) throws SQLiteException {
throwIfInvalid();
try {
return nativeColumnType(mStatement, column);
return nativeColumnType(mStatement, columnIndex);
} finally {
Reference.reachabilityFence(this);
}
@@ -499,17 +572,20 @@ public final class SQLiteRawStatement implements Closeable {
/**
* 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.
* @param column The index of a column in the result row. It is zero-based.
*
* @see <a href="http://sqlite.org/c3ref/column_name.html">sqlite3_column_name</a>
*
* @param columnIndex The index of a column in the result row. It is zero-based.
* @return The name of the column in the result row.
* @throws IllegalStateException if the statement is closed or this is a foreign thread.
* @throws SQLiteBindOrColumnIndexOutOfRangeException if the column is out of range.
* @throws SQLiteOutOfMemoryException if the database cannot allocate memory for the name.
*/
@NonNull
public String getName(int column) throws SQLiteException {
public String getColumnName(int columnIndex) throws SQLiteException {
throwIfInvalid();
try {
return nativeColumnName(mStatement, column);
return nativeColumnName(mStatement, columnIndex);
} finally {
Reference.reachabilityFence(this);
}
@@ -517,20 +593,24 @@ public final class SQLiteRawStatement implements Closeable {
/**
* 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. 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.
* @param column The index of a column in the result row. It is zero-based.
* 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.
*
* @see <a href="http://sqlite.org/c3ref/column_blob.html">sqlite3_column_bytes</a>
*
* @param columnIndex The index of a column in the result row. It is zero-based.
* @return The length, in bytes, of the value in the column.
* @throws IllegalStateException if the statement is closed or this is a foreign thread.
* @throws SQLiteBindOrColumnIndexOutOfRangeException if the column is out of range.
* @throws SQLiteException if a native error occurs.
*/
public int getLength(int column) throws SQLiteException {
public int getColumnLength(int columnIndex) throws SQLiteException {
throwIfInvalid();
try {
return nativeColumnBytes(mStatement, column);
return nativeColumnBytes(mStatement, columnIndex);
} finally {
Reference.reachabilityFence(this);
}
@@ -540,39 +620,23 @@ public final class SQLiteRawStatement implements Closeable {
* 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.
* @param column The index of a column in the result row. It is zero-based.
*
* The column value will be converted if it is not of type {@link #SQLITE_DATA_TYPE_BLOB}; see
* the sqlite documentation for details.
*
* @see <a href="http://sqlite.org/c3ref/column_blob.html">sqlite3_column_blob</a>
*
* @param columnIndex The index of a column in the result row. It is zero-based.
* @return 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.
* @throws SQLiteBindOrColumnIndexOutOfRangeException if the column is out of range.
* @throws SQLiteException if a native error occurs.
*/
@Nullable
public byte[] getBlob(int column) throws SQLiteException {
public byte[] getColumnBlob(int columnIndex) throws SQLiteException {
throwIfInvalid();
try {
return nativeColumnBlob(mStatement, column);
} finally {
Reference.reachabilityFence(this);
}
}
/**
* 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 until the buffer is full or the end of the blob value is reached.
* The function returns the number of bytes copied.
* @param column The index of a column in the result row. It is zero-based.
* @param buffer A pre-allocated array to be filled with the value of the column.
* @return the number of bytes that were copied
* @throws IllegalStateException if the statement is closed or this is a foreign thread.
* @throws SQLiteBindOrColumnIndexOutOfRangeException if the column is out of range.
* @throws SQLiteException if a native error occurs.
*/
public int getBlob(int column, @NonNull byte[] buffer) throws SQLiteException {
Objects.requireNonNull(buffer);
throwIfInvalid();
try {
return nativeColumnBuffer(mStatement, column, buffer, 0, buffer.length, 0);
return nativeColumnBlob(mStatement, columnIndex);
} finally {
Reference.reachabilityFence(this);
}
@@ -584,7 +648,13 @@ public final class SQLiteRawStatement implements Closeable {
* 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.
* @param column The index of a column in the result row. It is zero-based.
*
* The column value will be converted if it is not of type {@link #SQLITE_DATA_TYPE_BLOB}; see
* the sqlite documentation for details.
*
* @see <a href="http://sqlite.org/c3ref/column_blob.html">sqlite3_column_blob</a>
*
* @param columnIndex The index of a column in the result row. It is zero-based.
* @param buffer A pre-allocated array to be filled with the value of the column.
* @param offset An offset into the buffer: copying starts here.
* @param length The number of bytes to copy.
@@ -595,13 +665,14 @@ public final class SQLiteRawStatement implements Closeable {
* @throws SQLiteBindOrColumnIndexOutOfRangeException if the column is out of range.
* @throws SQLiteException if a native error occurs.
*/
public int getBlob(int column, @NonNull byte[] buffer, int offset, int length, int srcOffset)
public int readColumnBlob(int columnIndex, @NonNull byte[] buffer, int offset,
int length, int srcOffset)
throws SQLiteException {
Objects.requireNonNull(buffer);
throwIfInvalid();
throwIfInvalidBounds(buffer.length, offset, length);
try {
return nativeColumnBuffer(mStatement, column, buffer, offset, length, srcOffset);
return nativeColumnBuffer(mStatement, columnIndex, buffer, offset, length, srcOffset);
} finally {
Reference.reachabilityFence(this);
}
@@ -610,16 +681,22 @@ public final class SQLiteRawStatement implements Closeable {
/**
* Return the column value as a double. Column indices start at 0. This throws an exception
* if column is not in the result.
* @param column The index of a column in the result row. It is zero-based.
*
* The column value will be converted if it is not of type {@link #SQLITE_DATA_TYPE_FLOAT}; see
* the sqlite documentation for details.
*
* @see <a href="http://sqlite.org/c3ref/column_blob.html">sqlite3_column_double</a>
*
* @param columnIndex The index of a column in the result row. It is zero-based.
* @return The value of a column as a double.
* @throws IllegalStateException if the statement is closed or this is a foreign thread.
* @throws SQLiteBindOrColumnIndexOutOfRangeException if the column is out of range.
* @throws SQLiteException if a native error occurs.
*/
public double getDouble(int column) throws SQLiteException {
public double getColumnDouble(int columnIndex) throws SQLiteException {
throwIfInvalid();
try {
return nativeColumnDouble(mStatement, column);
return nativeColumnDouble(mStatement, columnIndex);
} finally {
Reference.reachabilityFence(this);
}
@@ -628,16 +705,22 @@ public final class SQLiteRawStatement implements Closeable {
/**
* Return the column value as a int. Column indices start at 0. This throws an exception if
* column is not in the result.
* @param column The index of a column in the result row. It is zero-based.
*
* The column value will be converted if it is not of type {@link #SQLITE_DATA_TYPE_INTEGER};
* see the sqlite documentation for details.
*
* @see <a href="http://sqlite.org/c3ref/column_blob.html">sqlite3_column_int</a>
*
* @param columnIndex The index of a column in the result row. It is zero-based.
* @return The value of the column as an int.
* @throws IllegalStateException if the statement is closed or this is a foreign thread.
* @throws SQLiteBindOrColumnIndexOutOfRangeException if the column is out of range.
* @throws SQLiteException if a native error occurs.
*/
public int getInt(int column) throws SQLiteException {
public int getColumnInt(int columnIndex) throws SQLiteException {
throwIfInvalid();
try {
return nativeColumnInt(mStatement, column);
return nativeColumnInt(mStatement, columnIndex);
} finally {
Reference.reachabilityFence(this);
}
@@ -646,16 +729,22 @@ public final class SQLiteRawStatement implements Closeable {
/**
* Return the column value as a long. Column indices start at 0. This throws an exception if
* column is not in the result.
* @param column The index of a column in the result row. It is zero-based.
*
* The column value will be converted if it is not of type {@link #SQLITE_DATA_TYPE_INTEGER};
* see the sqlite documentation for details.
*
* @see <a href="http://sqlite.org/c3ref/column_blob.html">sqlite3_column_long</a>
*
* @param columnIndex The index of a column in the result row. It is zero-based.
* @return The value of the column as an long.
* @throws IllegalStateException if the statement is closed or this is a foreign thread.
* @throws SQLiteBindOrColumnIndexOutOfRangeException if the column is out of range.
* @throws SQLiteException if a native error occurs.
*/
public long getLong(int column) throws SQLiteException {
public long getColumnLong(int columnIndex) throws SQLiteException {
throwIfInvalid();
try {
return nativeColumnLong(mStatement, column);
return nativeColumnLong(mStatement, columnIndex);
} finally {
Reference.reachabilityFence(this);
}
@@ -664,17 +753,23 @@ public final class SQLiteRawStatement implements Closeable {
/**
* Return the column value as a text. Column indices start at 0. This throws an exception if
* column is not in the result.
* @param column The index of a column in the result row. It is zero-based.
*
* The column value will be converted if it is not of type {@link #SQLITE_DATA_TYPE_TEXT}; see
* the sqlite documentation for details.
*
* @see <a href="http://sqlite.org/c3ref/column_blob.html">sqlite3_column_text16</a>
*
* @param columnIndex The index of a column in the result row. It is zero-based.
* @return The value of the column as a string.
* @throws IllegalStateException if the statement is closed or this is a foreign thread.
* @throws SQLiteBindOrColumnIndexOutOfRangeException if the column is out of range.
* @throws SQLiteException if a native error occurs.
*/
@NonNull
public String getText(int column) throws SQLiteException {
public String getColumnText(int columnIndex) throws SQLiteException {
throwIfInvalid();
try {
return nativeColumnText(mStatement, column);
return nativeColumnText(mStatement, columnIndex);
} finally {
Reference.reachabilityFence(this);
}
@@ -732,14 +827,16 @@ public final class SQLiteRawStatement implements Closeable {
private static native void nativeBindText(long stmt, int param, String val);
/**
* Methods that return information (including the values) of columns from the current result
* row.
* Methods that return information about the columns int the current result row.
*/
@FastNative
private static native int nativeColumnType(long stmt, int col);
@FastNative
private static native String nativeColumnName(long stmt, int col);
/**
* Methods that return information about the value columns in the current result row.
*/
@FastNative
private static native int nativeColumnBytes(long stmt, int col);

70
core/tests/coretests/src/android/database/sqlite/SQLiteRawStatementTest.java
View File

@@ -187,7 +187,7 @@ public class SQLiteRawStatementTest {
for (int i = 0; s.step() && i < 5; i++) {
boolean r = t.step();
assertTrue(r);
assertEquals(t.getInt(0), s.getInt(0));
assertEquals(t.getColumnInt(0), s.getColumnInt(0));
found++;
}
assertFalse(t.step());
@@ -240,7 +240,7 @@ public class SQLiteRawStatementTest {
try (SQLiteRawStatement s = mDatabase.createRawStatement(query)) {
boolean r = s.step();
assertTrue(r);
int rows = s.getInt(0);
int rows = s.getColumnInt(0);
assertEquals(10, rows);
}
mDatabase.setTransactionSuccessful();
@@ -254,10 +254,10 @@ public class SQLiteRawStatementTest {
final String query = "SELECT i, d, t FROM t1 WHERE t = 'text03value'";
try (SQLiteRawStatement s = mDatabase.createRawStatement(query)) {
assertTrue(s.step());
assertEquals(3, s.getResultColumnsCount());
int vi = s.getInt(0);
double vd = s.getDouble(1);
String vt = s.getText(2);
assertEquals(3, s.getResultColumnCount());
int vi = s.getColumnInt(0);
double vd = s.getColumnDouble(1);
String vt = s.getColumnText(2);
assertEquals(3 * 3, vi);
assertEquals(2.5 * 3, vd, 0.1);
assertEquals("text03value", vt);
@@ -273,10 +273,10 @@ public class SQLiteRawStatementTest {
final String query = "SELECT i, d, t FROM t1 WHERE i == 20";
try (SQLiteRawStatement s = mDatabase.createRawStatement(query)) {
assertTrue(s.step());
assertEquals(3, s.getResultColumnsCount());
assertEquals(20, s.getInt(0));
assertEquals(0.0, s.getDouble(1), 0.01);
assertEquals(null, s.getText(2));
assertEquals(3, s.getResultColumnCount());
assertEquals(20, s.getColumnInt(0));
assertEquals(0.0, s.getColumnDouble(1), 0.01);
assertEquals(null, s.getColumnText(2));
// No more rows.
assertFalse(s.step());
}
@@ -383,7 +383,7 @@ public class SQLiteRawStatementTest {
// Verify that a statement cannot be accessed once closed.
try {
s.getResultColumnsCount();
s.getResultColumnCount();
fail("accessed closed statement");
} catch (AssertionError e) {
// Pass on the fail from the try-block before the generic catch below can see it.
@@ -495,7 +495,7 @@ public class SQLiteRawStatementTest {
// Fetch the entire reference array.
s.bindInt(1, 1);
assertTrue(s.step());
byte[] a = s.getBlob(0);
byte[] a = s.getColumnBlob(0);
assertTrue(Arrays.equals(src, a));
s.reset();
@@ -503,21 +503,21 @@ public class SQLiteRawStatementTest {
s.bindInt(1, 2);
assertTrue(s.step());
byte[] c = new byte[src.length];
assertEquals(8, s.getBlob(0, c, 0, c.length, 0));
assertEquals(8, s.readColumnBlob(0, c, 0, c.length, 0));
assertTrue(Arrays.equals(src, 4, 4+8, c, 0, 0+8));
s.reset();
// Fetch the null.
s.bindInt(1, 3);
assertTrue(s.step());
assertEquals(null, s.getBlob(0));
assertEquals(null, s.getColumnBlob(0));
s.reset();
// Fetch the null and ensure the buffer is not modified.
for (int i = 0; i < c.length; i++) c[i] = 0;
s.bindInt(1, 3);
assertTrue(s.step());
assertEquals(0, s.getBlob(0, c, 0, c.length, 0));
assertEquals(0, s.readColumnBlob(0, c, 0, c.length, 0));
for (int i = 0; i < c.length; i++) assertEquals(0, c[i]);
s.reset();
}
@@ -553,17 +553,17 @@ public class SQLiteRawStatementTest {
mDatabase.beginTransaction();
try {
try (SQLiteRawStatement s = mDatabase.createRawStatement(sql)) {
assertEquals(3, s.bindParameterCount());
assertEquals(3, s.getParameterCount());
assertEquals(1, s.bindParameterIndex(":1"));
assertEquals(2, s.bindParameterIndex("?2"));
assertEquals(3, s.bindParameterIndex("@FOO"));
assertEquals(0, s.bindParameterIndex("@BAR"));
assertEquals(1, s.getParameterIndex(":1"));
assertEquals(2, s.getParameterIndex("?2"));
assertEquals(3, s.getParameterIndex("@FOO"));
assertEquals(0, s.getParameterIndex("@BAR"));
assertEquals(":1", s.bindParameterName(1));
assertEquals("?2", s.bindParameterName(2));
assertEquals("@FOO", s.bindParameterName(3));
assertEquals(null, s.bindParameterName(4));
assertEquals(":1", s.getParameterName(1));
assertEquals("?2", s.getParameterName(2));
assertEquals("@FOO", s.getParameterName(3));
assertEquals(null, s.getParameterName(4));
}
} finally {
mDatabase.endTransaction();
@@ -574,7 +574,7 @@ public class SQLiteRawStatementTest {
try {
try (SQLiteRawStatement s = mDatabase.createRawStatement(sql)) {
// Error case. The name is not supposed to be null.
assertEquals(0, s.bindParameterIndex(null));
assertEquals(0, s.getParameterIndex(null));
fail("expected a NullPointerException");
}
} catch (NullPointerException e) {
@@ -631,7 +631,7 @@ public class SQLiteRawStatementTest {
int found = 0;
try (var s = mDatabase.createRawStatement(query)) {
for (int i = 0; s.step(); i++) {
int vi = s.getInt(0);
int vi = s.getColumnInt(0);
int expected = i * 3;
assertEquals(expected, vi);
found = i;
@@ -705,7 +705,7 @@ public class SQLiteRawStatementTest {
for (int i = 0; i < loops; i++) {
try (var s = mDatabase.createRawStatement(query)) {
assertTrue(s.step());
int vi = s.getInt(0);
int vi = s.getColumnInt(0);
int expected = 0;
assertEquals(expected, vi);
}
@@ -775,7 +775,7 @@ public class SQLiteRawStatementTest {
for (int i = 0; i < size; i++) {
assertTrue(s.step());
for (int j = 0; j < 12; j++) {
assertEquals(s.getInt(j), wideVal(i, j));
assertEquals(s.getColumnInt(j), wideVal(i, j));
}
}
}
@@ -820,7 +820,7 @@ public class SQLiteRawStatementTest {
long start = SystemClock.uptimeMillis();
try (SQLiteRawStatement s = mDatabase.createRawStatement(query)) {
while (s.step()) {
s.getInt(0);
s.getColumnInt(0);
}
}
long elapsed = SystemClock.uptimeMillis() - start;
@@ -866,7 +866,7 @@ public class SQLiteRawStatementTest {
// No row is returned by this query.
assertFalse(r);
s.reset();
assertEquals(i + 1, mDatabase.lastInsertRowId());
assertEquals(i + 1, mDatabase.getLastInsertRowId());
}
}
mDatabase.setTransactionSuccessful();
@@ -889,7 +889,7 @@ public class SQLiteRawStatementTest {
// No row is returned by this query.
assertFalse(r);
s.reset();
assertEquals(size + i + 1, mDatabase.lastInsertRowId());
assertEquals(size + i + 1, mDatabase.getLastInsertRowId());
}
}
mDatabase.setTransactionSuccessful();
@@ -920,12 +920,12 @@ public class SQLiteRawStatementTest {
mDatabase.beginTransactionReadOnly();
try (SQLiteRawStatement s = mDatabase.createRawStatement(sql)) {
assertEquals(1, s.bindParameterIndex(head));
assertEquals(head, s.bindParameterName(1));
assertEquals(1, s.getParameterIndex(head));
assertEquals(head, s.getParameterName(1));
s.bindInt(1, 20);
assertTrue(s.step());
assertEquals(2, s.getInt(0));
assertEquals(cat, s.getName(0));
assertEquals(2, s.getColumnInt(0));
assertEquals(cat, s.getColumnName(0));
} finally {
mDatabase.endTransaction();
}