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