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 <= position <= 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