SQLiteStatement.java revision ccd954480c32e9f35357b66023ae912e7f3fa76b 
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
17package android.database.sqlite;
18
19import android.os.SystemClock;
20
21/**
22 * A pre-compiled statement against a {@link SQLiteDatabase} that can be reused.
23 * The statement cannot return multiple rows, but 1x1 result sets are allowed.
24 * Don't use SQLiteStatement constructor directly, please use
25 * {@link SQLiteDatabase#compileStatement(String)}
26 *<p>
27 * SQLiteStatement is not internally synchronized so code using a SQLiteStatement from multiple
28 * threads should perform its own synchronization when using the SQLiteStatement.
29 */
30public class SQLiteStatement extends SQLiteProgram
31{
32    /**
33     * Don't use SQLiteStatement constructor directly, please use
34     * {@link SQLiteDatabase#compileStatement(String)}
35     * @param db
36     * @param sql
37     */
38    /* package */ SQLiteStatement(SQLiteDatabase db, String sql) {
39        super(db, sql);
40    }
41
42    /**
43     * Execute this SQL statement, if it is not a query. For example,
44     * CREATE TABLE, DELTE, INSERT, etc.
45     *
46     * @throws android.database.SQLException If the SQL string is invalid for
47     *         some reason
48     */
49    public void execute() {
50        mDatabase.verifyDbIsOpen();
51        long timeStart = SystemClock.uptimeMillis();
52        mDatabase.lock();
53
54        acquireReference();
55        try {
56            mDatabase.closePendingStatements();
57            native_execute();
58            mDatabase.logTimeStat(mSql, timeStart);
59        } finally {
60            releaseReference();
61            mDatabase.unlock();
62        }
63    }
64
65    /**
66     * Execute this SQL statement and return the ID of the row inserted due to this call.
67     * The SQL statement should be an INSERT for this to be a useful call.
68     *
69     * @return the row ID of the last row inserted, if this insert is successful. -1 otherwise.
70     *
71     * @throws android.database.SQLException If the SQL string is invalid for
72     *         some reason
73     */
74    public long executeInsert() {
75        mDatabase.verifyDbIsOpen();
76        long timeStart = SystemClock.uptimeMillis();
77        mDatabase.lock();
78
79        acquireReference();
80        try {
81            mDatabase.closePendingStatements();
82            native_execute();
83            mDatabase.logTimeStat(mSql, timeStart);
84            return (mDatabase.lastChangeCount() > 0) ? mDatabase.lastInsertRow() : -1;
85        } finally {
86            releaseReference();
87            mDatabase.unlock();
88        }
89    }
90
91    /**
92     * Execute a statement that returns a 1 by 1 table with a numeric value.
93     * For example, SELECT COUNT(*) FROM table;
94     *
95     * @return The result of the query.
96     *
97     * @throws android.database.sqlite.SQLiteDoneException if the query returns zero rows
98     */
99    public long simpleQueryForLong() {
100        mDatabase.verifyDbIsOpen();
101        long timeStart = SystemClock.uptimeMillis();
102        mDatabase.lock();
103
104        acquireReference();
105        try {
106            mDatabase.closePendingStatements();
107            long retValue = native_1x1_long();
108            mDatabase.logTimeStat(mSql, timeStart);
109            return retValue;
110        } finally {
111            releaseReference();
112            mDatabase.unlock();
113        }
114    }
115
116    /**
117     * Execute a statement that returns a 1 by 1 table with a text value.
118     * For example, SELECT COUNT(*) FROM table;
119     *
120     * @return The result of the query.
121     *
122     * @throws android.database.sqlite.SQLiteDoneException if the query returns zero rows
123     */
124    public String simpleQueryForString() {
125        mDatabase.verifyDbIsOpen();
126        long timeStart = SystemClock.uptimeMillis();
127        mDatabase.lock();
128
129        acquireReference();
130        try {
131            mDatabase.closePendingStatements();
132            String retValue = native_1x1_string();
133            mDatabase.logTimeStat(mSql, timeStart);
134            return retValue;
135        } finally {
136            releaseReference();
137            mDatabase.unlock();
138        }
139    }
140
141    private final native void native_execute();
142    private final native long native_1x1_long();
143    private final native String native_1x1_string();
144}
145