1 /* 2 * Copyright (C) 2006 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.database.sqlite; 18 19 import android.os.ParcelFileDescriptor; 20 21 /** 22 * Represents a statement that can be executed against a database. The statement 23 * cannot return multiple rows or columns, but single value (1 x 1) result sets 24 * are supported. 25 * <p> 26 * This class is not thread-safe. 27 * </p> 28 */ 29 public final class SQLiteStatement extends SQLiteProgram { SQLiteStatement(SQLiteDatabase db, String sql, Object[] bindArgs)30 SQLiteStatement(SQLiteDatabase db, String sql, Object[] bindArgs) { 31 super(db, sql, bindArgs, null); 32 } 33 34 /** 35 * Execute this SQL statement, if it is not a SELECT / INSERT / DELETE / UPDATE, for example 36 * CREATE / DROP table, view, trigger, index etc. 37 * 38 * @throws android.database.SQLException If the SQL string is invalid for 39 * some reason 40 */ execute()41 public void execute() { 42 acquireReference(); 43 try { 44 getSession().execute(getSql(), getBindArgs(), getConnectionFlags(), null); 45 } catch (SQLiteDatabaseCorruptException ex) { 46 onCorruption(); 47 throw ex; 48 } finally { 49 releaseReference(); 50 } 51 } 52 53 /** 54 * Execute this SQL statement, if the the number of rows affected by execution of this SQL 55 * statement is of any importance to the caller - for example, UPDATE / DELETE SQL statements. 56 * 57 * @return the number of rows affected by this SQL statement execution. 58 * @throws android.database.SQLException If the SQL string is invalid for 59 * some reason 60 */ executeUpdateDelete()61 public int executeUpdateDelete() { 62 acquireReference(); 63 try { 64 return getSession().executeForChangedRowCount( 65 getSql(), getBindArgs(), getConnectionFlags(), null); 66 } catch (SQLiteDatabaseCorruptException ex) { 67 onCorruption(); 68 throw ex; 69 } finally { 70 releaseReference(); 71 } 72 } 73 74 /** 75 * Execute this SQL statement and return the ID of the row inserted due to this call. 76 * The SQL statement should be an INSERT for this to be a useful call. 77 * 78 * @return the row ID of the last row inserted, if this insert is successful. -1 otherwise. 79 * 80 * @throws android.database.SQLException If the SQL string is invalid for 81 * some reason 82 */ executeInsert()83 public long executeInsert() { 84 acquireReference(); 85 try { 86 return getSession().executeForLastInsertedRowId( 87 getSql(), getBindArgs(), getConnectionFlags(), null); 88 } catch (SQLiteDatabaseCorruptException ex) { 89 onCorruption(); 90 throw ex; 91 } finally { 92 releaseReference(); 93 } 94 } 95 96 /** 97 * Execute a statement that returns a 1 by 1 table with a numeric value. 98 * For example, SELECT COUNT(*) FROM table; 99 * 100 * @return The result of the query. 101 * 102 * @throws android.database.sqlite.SQLiteDoneException if the query returns zero rows 103 */ simpleQueryForLong()104 public long simpleQueryForLong() { 105 acquireReference(); 106 try { 107 return getSession().executeForLong( 108 getSql(), getBindArgs(), getConnectionFlags(), null); 109 } catch (SQLiteDatabaseCorruptException ex) { 110 onCorruption(); 111 throw ex; 112 } finally { 113 releaseReference(); 114 } 115 } 116 117 /** 118 * Execute a statement that returns a 1 by 1 table with a text value. 119 * For example, SELECT COUNT(*) FROM table; 120 * 121 * @return The result of the query. 122 * 123 * @throws android.database.sqlite.SQLiteDoneException if the query returns zero rows 124 */ simpleQueryForString()125 public String simpleQueryForString() { 126 acquireReference(); 127 try { 128 return getSession().executeForString( 129 getSql(), getBindArgs(), getConnectionFlags(), null); 130 } catch (SQLiteDatabaseCorruptException ex) { 131 onCorruption(); 132 throw ex; 133 } finally { 134 releaseReference(); 135 } 136 } 137 138 /** 139 * Executes a statement that returns a 1 by 1 table with a blob value. 140 * 141 * @return A read-only file descriptor for a copy of the blob value, or {@code null} 142 * if the value is null or could not be read for some reason. 143 * 144 * @throws android.database.sqlite.SQLiteDoneException if the query returns zero rows 145 */ simpleQueryForBlobFileDescriptor()146 public ParcelFileDescriptor simpleQueryForBlobFileDescriptor() { 147 acquireReference(); 148 try { 149 return getSession().executeForBlobFileDescriptor( 150 getSql(), getBindArgs(), getConnectionFlags(), null); 151 } catch (SQLiteDatabaseCorruptException ex) { 152 onCorruption(); 153 throw ex; 154 } finally { 155 releaseReference(); 156 } 157 } 158 159 @Override toString()160 public String toString() { 161 return "SQLiteProgram: " + getSql(); 162 } 163 } 164