diff --git a/core/api/current.txt b/core/api/current.txt index c2bc5a2426af9..82b880a021115 100644 --- a/core/api/current.txt +++ b/core/api/current.txt @@ -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> 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); diff --git a/core/java/android/database/sqlite/SQLiteDatabase.java b/core/java/android/database/sqlite/SQLiteDatabase.java index 026b8c2aa9b16..eceec34ba0f4b 100644 --- a/core/java/android/database/sqlite/SQLiteDatabase.java +++ b/core/java/android/database/sqlite/SQLiteDatabase.java @@ -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 sqlite3_last_insert_rowid + * * @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(); } diff --git a/core/java/android/database/sqlite/SQLiteRawStatement.java b/core/java/android/database/sqlite/SQLiteRawStatement.java index 6b43788cd4790..165f1810c8943 100644 --- a/core/java/android/database/sqlite/SQLiteRawStatement.java +++ b/core/java/android/database/sqlite/SQLiteRawStatement.java @@ -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. + *

* 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(); * } * - * Note that this class is unrelated to {@link SQLiteStatement}. - * @hide + * Note that {@link SQLiteRawStatement} is unrelated to {@link SQLiteStatement}. + * + * @see sqlite3_stmt */ 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 sqlite3_step + * * @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 sqlite3_reset + * * @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 sqlite3_clear_bindings + * * @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 + * sqlite3_bind_parameter_count + * * @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 + * sqlite3_bind_parameter_index + * * @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 + * sqlite3_bind_parameter_name + * + * @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 sqlite3_bind_blob + * + * @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 sqlite3_bind_blob + * + * @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 sqlite3_bind_double + * + * @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 sqlite3_bind_int + * + * @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 sqlite3_bind_int64 + * * @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 sqlite3_bind_null + * + * @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 sqlite3_bind_text16 + * + * @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 sqlite3_column_count + * * @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 sqlite3_column_type + * + * @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 sqlite3_column_name + * + * @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 sqlite3_column_bytes + * + * @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 sqlite3_column_blob + * + * @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 sqlite3_column_blob + * + * @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 sqlite3_column_double + * + * @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 sqlite3_column_int + * + * @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 sqlite3_column_long + * + * @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 sqlite3_column_text16 + * + * @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); diff --git a/core/tests/coretests/src/android/database/sqlite/SQLiteRawStatementTest.java b/core/tests/coretests/src/android/database/sqlite/SQLiteRawStatementTest.java index 944e2b06a152c..59a1643c061f3 100644 --- a/core/tests/coretests/src/android/database/sqlite/SQLiteRawStatementTest.java +++ b/core/tests/coretests/src/android/database/sqlite/SQLiteRawStatementTest.java @@ -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(); }