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.annotation.UnsupportedAppUsage; 20 import android.os.ParcelFileDescriptor; 21 22 /** 23 * Represents a statement that can be executed against a database. The statement 24 * cannot return multiple rows or columns, but single value (1 x 1) result sets 25 * are supported. 26 * <p> 27 * This class is not thread-safe. 28 * </p> 29 */ 30 public final class SQLiteStatement extends SQLiteProgram { 31 @UnsupportedAppUsage SQLiteStatement(SQLiteDatabase db, String sql, Object[] bindArgs)32 SQLiteStatement(SQLiteDatabase db, String sql, Object[] bindArgs) { 33 super(db, sql, bindArgs, null); 34 } 35 36 /** 37 * Execute this SQL statement, if it is not a SELECT / INSERT / DELETE / UPDATE, for example 38 * CREATE / DROP table, view, trigger, index etc. 39 * 40 * @throws android.database.SQLException If the SQL string is invalid for 41 * some reason 42 */ execute()43 public void execute() { 44 acquireReference(); 45 try { 46 getSession().execute(getSql(), getBindArgs(), getConnectionFlags(), null); 47 } catch (SQLiteDatabaseCorruptException ex) { 48 onCorruption(); 49 throw ex; 50 } finally { 51 releaseReference(); 52 } 53 } 54 55 /** 56 * Execute this SQL statement, if the number of rows affected by execution of this SQL 57 * statement is of any importance to the caller - for example, UPDATE / DELETE SQL statements. 58 * 59 * @return the number of rows affected by this SQL statement execution. 60 * @throws android.database.SQLException If the SQL string is invalid for 61 * some reason 62 */ executeUpdateDelete()63 public int executeUpdateDelete() { 64 acquireReference(); 65 try { 66 return getSession().executeForChangedRowCount( 67 getSql(), getBindArgs(), getConnectionFlags(), null); 68 } catch (SQLiteDatabaseCorruptException ex) { 69 onCorruption(); 70 throw ex; 71 } finally { 72 releaseReference(); 73 } 74 } 75 76 /** 77 * Execute this SQL statement and return the ID of the row inserted due to this call. 78 * The SQL statement should be an INSERT for this to be a useful call. 79 * 80 * @return the row ID of the last row inserted, if this insert is successful. -1 otherwise. 81 * 82 * @throws android.database.SQLException If the SQL string is invalid for 83 * some reason 84 */ executeInsert()85 public long executeInsert() { 86 acquireReference(); 87 try { 88 return getSession().executeForLastInsertedRowId( 89 getSql(), getBindArgs(), getConnectionFlags(), null); 90 } catch (SQLiteDatabaseCorruptException ex) { 91 onCorruption(); 92 throw ex; 93 } finally { 94 releaseReference(); 95 } 96 } 97 98 /** 99 * Execute a statement that returns a 1 by 1 table with a numeric value. 100 * For example, SELECT COUNT(*) FROM table; 101 * 102 * @return The result of the query. 103 * 104 * @throws android.database.sqlite.SQLiteDoneException if the query returns zero rows 105 */ simpleQueryForLong()106 public long simpleQueryForLong() { 107 acquireReference(); 108 try { 109 return getSession().executeForLong( 110 getSql(), getBindArgs(), getConnectionFlags(), null); 111 } catch (SQLiteDatabaseCorruptException ex) { 112 onCorruption(); 113 throw ex; 114 } finally { 115 releaseReference(); 116 } 117 } 118 119 /** 120 * Execute a statement that returns a 1 by 1 table with a text value. 121 * For example, SELECT COUNT(*) FROM table; 122 * 123 * @return The result of the query. 124 * 125 * @throws android.database.sqlite.SQLiteDoneException if the query returns zero rows 126 */ simpleQueryForString()127 public String simpleQueryForString() { 128 acquireReference(); 129 try { 130 return getSession().executeForString( 131 getSql(), getBindArgs(), getConnectionFlags(), null); 132 } catch (SQLiteDatabaseCorruptException ex) { 133 onCorruption(); 134 throw ex; 135 } finally { 136 releaseReference(); 137 } 138 } 139 140 /** 141 * Executes a statement that returns a 1 by 1 table with a blob value. 142 * 143 * @return A read-only file descriptor for a copy of the blob value, or {@code null} 144 * if the value is null or could not be read for some reason. 145 * 146 * @throws android.database.sqlite.SQLiteDoneException if the query returns zero rows 147 */ simpleQueryForBlobFileDescriptor()148 public ParcelFileDescriptor simpleQueryForBlobFileDescriptor() { 149 acquireReference(); 150 try { 151 return getSession().executeForBlobFileDescriptor( 152 getSql(), getBindArgs(), getConnectionFlags(), null); 153 } catch (SQLiteDatabaseCorruptException ex) { 154 onCorruption(); 155 throw ex; 156 } finally { 157 releaseReference(); 158 } 159 } 160 161 @Override toString()162 public String toString() { 163 return "SQLiteProgram: " + getSql(); 164 } 165 } 166