Stmt.java revision 7a647e8547e57ca573541be55b3728ef7ce376fe 
1package SQLite;
2
3/**
4 * Class to represent compiled SQLite3 statement.
5 *
6 * Note, that all native methods of this class are
7 * not synchronized, i.e. it is up to the caller
8 * to ensure that only one thread is in these
9 * methods at any one time.
10 */
11
12public class Stmt {
13
14    /**
15     * Internal handle for the SQLite3 statement.
16     */
17
18    private long handle = 0;
19
20    /**
21     * Internal last error code for prepare()/step() methods.
22     */
23
24    protected int error_code = 0;
25
26    /**
27     * Prepare the next SQL statement for the Stmt instance.
28     * @return true when the next piece of the SQL statement sequence
29     * has been prepared, false on end of statement sequence.
30     */
31
32    public native boolean prepare() throws SQLite.Exception;
33
34    /**
35     * Perform one step of compiled SQLite3 statement.
36     *
37     * Example:<BR>
38     * <PRE>
39     *   ...
40     *   try {
41     *     Stmt s = db.prepare("select * from x; select * from y;");
42     *     s.bind(...);
43     *     ...
44     *     s.bind(...);
45     *     while (s.step(cb)) {
46     *       Object o = s.value(...);
47     *       ...
48     *     }
49     *     // s.reset() for re-execution or
50     *     // s.prepare() for the next piece of SQL
51     *     while (s.prepare()) {
52     *       s.bind(...);
53     *       ...
54     *       s.bind(...);
55     *       while (s.step(cb)) {
56     *         Object o = s.value(...);
57     *         ...
58     *       }
59     *     }
60     *   } catch (SQLite.Exception e) {
61     *     s.close();
62     *   }
63     * </PRE>
64     *
65     * @return true when row data is available, false on end
66     * of result set.
67     */
68
69    public native boolean step() throws SQLite.Exception;
70
71    /**
72     * Close the compiled SQLite3 statement.
73     */
74
75    public native void close() throws SQLite.Exception;
76
77    /**
78     * Reset the compiled SQLite3 statement without
79     * clearing parameter bindings.
80     */
81
82    public native void reset() throws SQLite.Exception;
83
84    /**
85     * Clear all bound parameters of the compiled SQLite3 statement.
86     */
87
88    public native void clear_bindings() throws SQLite.Exception;
89
90    /**
91     * Bind positional integer value to compiled SQLite3 statement.
92     * @param pos parameter index, 1-based
93     * @param value value of parameter
94     */
95
96    public native void bind(int pos, int value) throws SQLite.Exception;
97
98    /**
99     * Bind positional long value to compiled SQLite3 statement.
100     * @param pos parameter index, 1-based
101     * @param value value of parameter
102     */
103
104    public native void bind(int pos, long value) throws SQLite.Exception;
105
106    /**
107     * Bind positional double value to compiled SQLite3 statement.
108     * @param pos parameter index, 1-based
109     * @param value value of parameter
110     */
111
112    public native void bind(int pos, double value) throws SQLite.Exception;
113
114    /**
115     * Bind positional byte array to compiled SQLite3 statement.
116     * @param pos parameter index, 1-based
117     * @param value value of parameter, may be null
118     */
119
120    public native void bind(int pos, byte[] value) throws SQLite.Exception;
121
122    /**
123     * Bind positional String to compiled SQLite3 statement.
124     * @param pos parameter index, 1-based
125     * @param value value of parameter, may be null
126     */
127
128    public native void bind(int pos, String value) throws SQLite.Exception;
129
130    /**
131     * Bind positional SQL null to compiled SQLite3 statement.
132     * @param pos parameter index, 1-based
133     */
134
135    public native void bind(int pos) throws SQLite.Exception;
136
137    /**
138     * Bind positional zero'ed blob to compiled SQLite3 statement.
139     * @param pos parameter index, 1-based
140     * @param length byte size of zero blob
141     */
142
143    public native void bind_zeroblob(int pos, int length)
144	throws SQLite.Exception;
145
146    /**
147     * Return number of parameters in compiled SQLite3 statement.
148     * @return int number of parameters
149     */
150
151    public native int bind_parameter_count() throws SQLite.Exception;
152
153    /**
154     * Return name of parameter in compiled SQLite3 statement.
155     * @param pos parameter index, 1-based
156     * @return String parameter name
157     */
158
159    public native String bind_parameter_name(int pos) throws SQLite.Exception;
160
161    /**
162     * Return index of named parameter in compiled SQLite3 statement.
163     * @param name of parameter
164     * @return int index of parameter, 1-based
165     */
166
167    public native int bind_parameter_index(String name)
168	throws SQLite.Exception;
169
170
171    /**
172     * Retrieve integer column from exec'ed SQLite3 statement.
173     * @param col column number, 0-based
174     * @return int column value
175     */
176
177    public native int column_int(int col) throws SQLite.Exception;
178
179    /**
180     * Retrieve long column from exec'ed SQLite3 statement.
181     * @param col column number, 0-based
182     * @return long column value
183     */
184    public native long column_long(int col) throws SQLite.Exception;
185
186    /**
187     * Retrieve double column from exec'ed SQLite3 statement.
188     * @param col column number, 0-based
189     * @return double column value
190     */
191    public native double column_double(int col) throws SQLite.Exception;
192
193    /**
194     * Retrieve blob column from exec'ed SQLite3 statement.
195     * @param col column number, 0-based
196     * @return byte[] column value
197     */
198    public native byte[] column_bytes(int col) throws SQLite.Exception;
199
200    /**
201     * Retrieve string column from exec'ed SQLite3 statement.
202     * @param col column number, 0-based
203     * @return String column value
204     */
205    public native String column_string(int col) throws SQLite.Exception;
206
207    /**
208     * Retrieve column type from exec'ed SQLite3 statement.
209     * @param col column number, 0-based
210     * @return column type code, e.g. SQLite.Constants.SQLITE_INTEGER
211     */
212    public native int column_type(int col) throws SQLite.Exception;
213
214    /**
215     * Retrieve number of columns of exec'ed SQLite3 statement.
216     * @return int number of columns
217     */
218
219    public native int column_count() throws SQLite.Exception;
220
221    /**
222     * Retrieve column data as object from exec'ed SQLite3 statement.
223     * @param col column number, 0-based
224     * @return Object or null
225     */
226
227    public Object column(int col) throws SQLite.Exception {
228        switch (column_type(col)) {
229	case Constants.SQLITE_INTEGER:
230	    return new Long(column_long(col));
231	case Constants.SQLITE_FLOAT:
232	    return new Double(column_double(col));
233	case Constants.SQLITE_BLOB:
234	    return column_bytes(col);
235	case Constants.SQLITE3_TEXT:
236	    return column_string(col);
237	}
238	return null;
239    }
240
241    /**
242     * Return table name of column of SQLite3 statement.
243     * @param col column number, 0-based
244     * @return String or null
245     */
246
247    public native String column_table_name(int col) throws SQLite.Exception;
248
249    /**
250     * Return database name of column of SQLite3 statement.
251     * @param col column number, 0-based
252     * @return String or null
253     */
254
255    public native String column_database_name(int col) throws SQLite.Exception;
256
257    /**
258     * Return declared column type of SQLite3 statement.
259     * @param col column number, 0-based
260     * @return String or null
261     */
262
263    public native String column_decltype(int col) throws SQLite.Exception;
264
265    /**
266     * Return origin column name of column of SQLite3 statement.
267     * @param col column number, 0-based
268     * @return String or null
269     */
270
271    public native String column_origin_name(int col) throws SQLite.Exception;
272
273    /**
274     * Destructor for object.
275     */
276
277    protected native void finalize();
278
279    /**
280     * Internal native initializer.
281     */
282
283    private static native void internal_init();
284
285    static {
286	internal_init();
287    }
288}
289