Cursor.java revision 81e9276a479fd3a5ccc3129505c0fb018941934b
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;
18
19import android.content.ContentResolver;
20import android.net.Uri;
21import android.os.Bundle;
22
23/**
24 * This interface provides random read-write access to the result set returned
25 * by a database query.
26 *
27 * Cursor implementations are not required to be synchronized so code using a Cursor from multiple
28 * threads should perform its own synchronization when using the Cursor.
29 */
30public interface Cursor {
31    /*
32     * Values returned by {@link #getType(int)}.
33     * These should be consistent with the corresponding types defined in CursorWindow.h
34     */
35    /** Value returned by {@link #getType(int)} if the specified column is null */
36    static final int FIELD_TYPE_NULL = 0;
37
38    /** Value returned by {@link #getType(int)} if the specified  column type is integer */
39    static final int FIELD_TYPE_INTEGER = 1;
40
41    /** Value returned by {@link #getType(int)} if the specified column type is float */
42    static final int FIELD_TYPE_FLOAT = 2;
43
44    /** Value returned by {@link #getType(int)} if the specified column type is string */
45    static final int FIELD_TYPE_STRING = 3;
46
47    /** Value returned by {@link #getType(int)} if the specified column type is blob */
48    static final int FIELD_TYPE_BLOB = 4;
49
50    /**
51     * Returns the numbers of rows in the cursor.
52     *
53     * @return the number of rows in the cursor.
54     */
55    int getCount();
56
57    /**
58     * Returns the current position of the cursor in the row set.
59     * The value is zero-based. When the row set is first returned the cursor
60     * will be at positon -1, which is before the first row. After the
61     * last row is returned another call to next() will leave the cursor past
62     * the last entry, at a position of count().
63     *
64     * @return the current cursor position.
65     */
66    int getPosition();
67
68    /**
69     * Move the cursor by a relative amount, forward or backward, from the
70     * current position. Positive offsets move forwards, negative offsets move
71     * backwards. If the final position is outside of the bounds of the result
72     * set then the resultant position will be pinned to -1 or count() depending
73     * on whether the value is off the front or end of the set, respectively.
74     *
75     * <p>This method will return true if the requested destination was
76     * reachable, otherwise, it returns false. For example, if the cursor is at
77     * currently on the second entry in the result set and move(-5) is called,
78     * the position will be pinned at -1, and false will be returned.
79     *
80     * @param offset the offset to be applied from the current position.
81     * @return whether the requested move fully succeeded.
82     */
83    boolean move(int offset);
84
85    /**
86     * Move the cursor to an absolute position. The valid
87     * range of values is -1 &lt;= position &lt;= count.
88     *
89     * <p>This method will return true if the request destination was reachable,
90     * otherwise, it returns false.
91     *
92     * @param position the zero-based position to move to.
93     * @return whether the requested move fully succeeded.
94     */
95    boolean moveToPosition(int position);
96
97    /**
98     * Move the cursor to the first row.
99     *
100     * <p>This method will return false if the cursor is empty.
101     *
102     * @return whether the move succeeded.
103     */
104    boolean moveToFirst();
105
106    /**
107     * Move the cursor to the last row.
108     *
109     * <p>This method will return false if the cursor is empty.
110     *
111     * @return whether the move succeeded.
112     */
113    boolean moveToLast();
114
115    /**
116     * Move the cursor to the next row.
117     *
118     * <p>This method will return false if the cursor is already past the
119     * last entry in the result set.
120     *
121     * @return whether the move succeeded.
122     */
123    boolean moveToNext();
124
125    /**
126     * Move the cursor to the previous row.
127     *
128     * <p>This method will return false if the cursor is already before the
129     * first entry in the result set.
130     *
131     * @return whether the move succeeded.
132     */
133    boolean moveToPrevious();
134
135    /**
136     * Returns whether the cursor is pointing to the first row.
137     *
138     * @return whether the cursor is pointing at the first entry.
139     */
140    boolean isFirst();
141
142    /**
143     * Returns whether the cursor is pointing to the last row.
144     *
145     * @return whether the cursor is pointing at the last entry.
146     */
147    boolean isLast();
148
149    /**
150     * Returns whether the cursor is pointing to the position before the first
151     * row.
152     *
153     * @return whether the cursor is before the first result.
154     */
155    boolean isBeforeFirst();
156
157    /**
158     * Returns whether the cursor is pointing to the position after the last
159     * row.
160     *
161     * @return whether the cursor is after the last result.
162     */
163    boolean isAfterLast();
164
165    /**
166     * Returns the zero-based index for the given column name, or -1 if the column doesn't exist.
167     * If you expect the column to exist use {@link #getColumnIndexOrThrow(String)} instead, which
168     * will make the error more clear.
169     *
170     * @param columnName the name of the target column.
171     * @return the zero-based column index for the given column name, or -1 if
172     * the column name does not exist.
173     * @see #getColumnIndexOrThrow(String)
174     */
175    int getColumnIndex(String columnName);
176
177    /**
178     * Returns the zero-based index for the given column name, or throws
179     * {@link IllegalArgumentException} if the column doesn't exist. If you're not sure if
180     * a column will exist or not use {@link #getColumnIndex(String)} and check for -1, which
181     * is more efficient than catching the exceptions.
182     *
183     * @param columnName the name of the target column.
184     * @return the zero-based column index for the given column name
185     * @see #getColumnIndex(String)
186     * @throws IllegalArgumentException if the column does not exist
187     */
188    int getColumnIndexOrThrow(String columnName) throws IllegalArgumentException;
189
190    /**
191     * Returns the column name at the given zero-based column index.
192     *
193     * @param columnIndex the zero-based index of the target column.
194     * @return the column name for the given column index.
195     */
196    String getColumnName(int columnIndex);
197
198    /**
199     * Returns a string array holding the names of all of the columns in the
200     * result set in the order in which they were listed in the result.
201     *
202     * @return the names of the columns returned in this query.
203     */
204    String[] getColumnNames();
205
206    /**
207     * Return total number of columns
208     * @return number of columns
209     */
210    int getColumnCount();
211
212    /**
213     * Returns the value of the requested column as a byte array.
214     *
215     * <p>The result and whether this method throws an exception when the
216     * column value is null or the column type is not a blob type is
217     * implementation-defined.
218     *
219     * @param columnIndex the zero-based index of the target column.
220     * @return the value of that column as a byte array.
221     */
222    byte[] getBlob(int columnIndex);
223
224    /**
225     * Returns the value of the requested column as a String.
226     *
227     * <p>The result and whether this method throws an exception when the
228     * column value is null or the column type is not a string type is
229     * implementation-defined.
230     *
231     * @param columnIndex the zero-based index of the target column.
232     * @return the value of that column as a String.
233     */
234    String getString(int columnIndex);
235
236    /**
237     * Retrieves the requested column text and stores it in the buffer provided.
238     * If the buffer size is not sufficient, a new char buffer will be allocated
239     * and assigned to CharArrayBuffer.data
240     * @param columnIndex the zero-based index of the target column.
241     *        if the target column is null, return buffer
242     * @param buffer the buffer to copy the text into.
243     */
244    void copyStringToBuffer(int columnIndex, CharArrayBuffer buffer);
245
246    /**
247     * Returns the value of the requested column as a short.
248     *
249     * <p>The result and whether this method throws an exception when the
250     * column value is null, the column type is not an integral type, or the
251     * integer value is outside the range [<code>Short.MIN_VALUE</code>,
252     * <code>Short.MAX_VALUE</code>] is implementation-defined.
253     *
254     * @param columnIndex the zero-based index of the target column.
255     * @return the value of that column as a short.
256     */
257    short getShort(int columnIndex);
258
259    /**
260     * Returns the value of the requested column as an int.
261     *
262     * <p>The result and whether this method throws an exception when the
263     * column value is null, the column type is not an integral type, or the
264     * integer value is outside the range [<code>Integer.MIN_VALUE</code>,
265     * <code>Integer.MAX_VALUE</code>] is implementation-defined.
266     *
267     * @param columnIndex the zero-based index of the target column.
268     * @return the value of that column as an int.
269     */
270    int getInt(int columnIndex);
271
272    /**
273     * Returns the value of the requested column as a long.
274     *
275     * <p>The result and whether this method throws an exception when the
276     * column value is null, the column type is not an integral type, or the
277     * integer value is outside the range [<code>Long.MIN_VALUE</code>,
278     * <code>Long.MAX_VALUE</code>] is implementation-defined.
279     *
280     * @param columnIndex the zero-based index of the target column.
281     * @return the value of that column as a long.
282     */
283    long getLong(int columnIndex);
284
285    /**
286     * Returns the value of the requested column as a float.
287     *
288     * <p>The result and whether this method throws an exception when the
289     * column value is null, the column type is not a floating-point type, or the
290     * floating-point value is not representable as a <code>float</code> value is
291     * implementation-defined.
292     *
293     * @param columnIndex the zero-based index of the target column.
294     * @return the value of that column as a float.
295     */
296    float getFloat(int columnIndex);
297
298    /**
299     * Returns the value of the requested column as a double.
300     *
301     * <p>The result and whether this method throws an exception when the
302     * column value is null, the column type is not a floating-point type, or the
303     * floating-point value is not representable as a <code>double</code> value is
304     * implementation-defined.
305     *
306     * @param columnIndex the zero-based index of the target column.
307     * @return the value of that column as a double.
308     */
309    double getDouble(int columnIndex);
310
311    /**
312     * Returns data type of the given column's value.
313     * The preferred type of the column is returned but the data may be converted to other types
314     * as documented in the get-type methods such as {@link #getInt(int)}, {@link #getFloat(int)}
315     * etc.
316     *<p>
317     * Returned column types are
318     * <ul>
319     *   <li>{@link #FIELD_TYPE_NULL}</li>
320     *   <li>{@link #FIELD_TYPE_INTEGER}</li>
321     *   <li>{@link #FIELD_TYPE_FLOAT}</li>
322     *   <li>{@link #FIELD_TYPE_STRING}</li>
323     *   <li>{@link #FIELD_TYPE_BLOB}</li>
324     *</ul>
325     *</p>
326     *
327     * @param columnIndex the zero-based index of the target column.
328     * @return column value type
329     */
330    int getType(int columnIndex);
331
332    /**
333     * Returns <code>true</code> if the value in the indicated column is null.
334     *
335     * @param columnIndex the zero-based index of the target column.
336     * @return whether the column value is null.
337     */
338    boolean isNull(int columnIndex);
339
340    /**
341     * Deactivates the Cursor, making all calls on it fail until {@link #requery} is called.
342     * Inactive Cursors use fewer resources than active Cursors.
343     * Calling {@link #requery} will make the cursor active again.
344     * @deprecated Since {@link #requery()} is deprecated, so too is this.
345     */
346    void deactivate();
347
348    /**
349     * Performs the query that created the cursor again, refreshing its
350     * contents. This may be done at any time, including after a call to {@link
351     * #deactivate}.
352     *
353     * Since this method could execute a query on the database and potentially take
354     * a while, it could cause ANR if it is called on Main (UI) thread.
355     * A warning is printed if this method is being executed on Main thread.
356     *
357     * @return true if the requery succeeded, false if not, in which case the
358     *         cursor becomes invalid.
359     * @deprecated Don't use this. Just request a new cursor, so you can do this
360     * asynchronously and update your list view once the new cursor comes back.
361     */
362    @Deprecated
363    boolean requery();
364
365    /**
366     * Closes the Cursor, releasing all of its resources and making it completely invalid.
367     * Unlike {@link #deactivate()} a call to {@link #requery()} will not make the Cursor valid
368     * again.
369     */
370    void close();
371
372    /**
373     * return true if the cursor is closed
374     * @return true if the cursor is closed.
375     */
376    boolean isClosed();
377
378    /**
379     * Register an observer that is called when changes happen to the content backing this cursor.
380     * Typically the data set won't change until {@link #requery()} is called.
381     *
382     * @param observer the object that gets notified when the content backing the cursor changes.
383     * @see #unregisterContentObserver(ContentObserver)
384     */
385    void registerContentObserver(ContentObserver observer);
386
387    /**
388     * Unregister an observer that has previously been registered with this
389     * cursor via {@link #registerContentObserver}.
390     *
391     * @param observer the object to unregister.
392     * @see #registerContentObserver(ContentObserver)
393     */
394    void unregisterContentObserver(ContentObserver observer);
395
396    /**
397     * Register an observer that is called when changes happen to the contents
398     * of the this cursors data set, for example, when the data set is changed via
399     * {@link #requery()}, {@link #deactivate()}, or {@link #close()}.
400     *
401     * @param observer the object that gets notified when the cursors data set changes.
402     * @see #unregisterDataSetObserver(DataSetObserver)
403     */
404    void registerDataSetObserver(DataSetObserver observer);
405
406    /**
407     * Unregister an observer that has previously been registered with this
408     * cursor via {@link #registerContentObserver}.
409     *
410     * @param observer the object to unregister.
411     * @see #registerDataSetObserver(DataSetObserver)
412     */
413    void unregisterDataSetObserver(DataSetObserver observer);
414
415    /**
416     * Register to watch a content URI for changes. This can be the URI of a specific data row (for
417     * example, "content://my_provider_type/23"), or a a generic URI for a content type.
418     *
419     * @param cr The content resolver from the caller's context. The listener attached to
420     * this resolver will be notified.
421     * @param uri The content URI to watch.
422     */
423    void setNotificationUri(ContentResolver cr, Uri uri);
424
425    /**
426     * onMove() will only be called across processes if this method returns true.
427     * @return whether all cursor movement should result in a call to onMove().
428     */
429    boolean getWantsAllOnMoveCalls();
430
431    /**
432     * Returns a bundle of extra values. This is an optional way for cursors to provide out-of-band
433     * metadata to their users. One use of this is for reporting on the progress of network requests
434     * that are required to fetch data for the cursor.
435     *
436     * <p>These values may only change when requery is called.
437     * @return cursor-defined values, or {@link android.os.Bundle#EMPTY Bundle.EMPTY} if there
438     *         are no values. Never <code>null</code>.
439     */
440    Bundle getExtras();
441
442    /**
443     * This is an out-of-band way for the the user of a cursor to communicate with the cursor. The
444     * structure of each bundle is entirely defined by the cursor.
445     *
446     * <p>One use of this is to tell a cursor that it should retry its network request after it
447     * reported an error.
448     * @param extras extra values, or {@link android.os.Bundle#EMPTY Bundle.EMPTY}.
449     *         Never <code>null</code>.
450     * @return extra values, or {@link android.os.Bundle#EMPTY Bundle.EMPTY}.
451     *         Never <code>null</code>.
452     */
453    Bundle respond(Bundle extras);
454}
455