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.compat.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