Cursor.java revision 54b6cfa9a9e5b861a9930af873580d6dc20f773c
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 23import java.util.Map; 24 25/** 26 * This interface provides random read-write access to the result set returned 27 * by a database query. 28 */ 29public interface Cursor { 30 /** 31 * Returns the numbers of rows in the cursor. 32 * 33 * @return the number of rows in the cursor. 34 */ 35 int getCount(); 36 37 /** 38 * Returns the current position of the cursor in the row set. 39 * The value is zero-based. When the row set is first returned the cursor 40 * will be at positon -1, which is before the first row. After the 41 * last row is returned another call to next() will leave the cursor past 42 * the last entry, at a position of count(). 43 * 44 * @return the current cursor position. 45 */ 46 int getPosition(); 47 48 /** 49 * Move the cursor by a relative amount, forward or backward, from the 50 * current position. Positive offsets move forwards, negative offsets move 51 * backwards. If the final position is outside of the bounds of the result 52 * set then the resultant position will be pinned to -1 or count() depending 53 * on whether the value is off the front or end of the set, respectively. 54 * 55 * <p>This method will return true if the requested destination was 56 * reachable, otherwise, it returns false. For example, if the cursor is at 57 * currently on the second entry in the result set and move(-5) is called, 58 * the position will be pinned at -1, and false will be returned. 59 * 60 * @param offset the offset to be applied from the current position. 61 * @return whether the requested move fully succeeded. 62 */ 63 boolean move(int offset); 64 65 /** 66 * Move the cursor to an absolute position. The valid 67 * range of values is -1 <= position <= count. 68 * 69 * <p>This method will return true if the request destination was reachable, 70 * otherwise, it returns false. 71 * 72 * @param position the zero-based position to move to. 73 * @return whether the requested move fully succeeded. 74 */ 75 boolean moveToPosition(int position); 76 77 /** 78 * Move the cursor to the first row. 79 * 80 * <p>This method will return false if the cursor is empty. 81 * 82 * @return whether the move succeeded. 83 */ 84 boolean moveToFirst(); 85 86 /** 87 * Move the cursor to the last row. 88 * 89 * <p>This method will return false if the cursor is empty. 90 * 91 * @return whether the move succeeded. 92 */ 93 boolean moveToLast(); 94 95 /** 96 * Move the cursor to the next row. 97 * 98 * <p>This method will return false if the cursor is already past the 99 * last entry in the result set. 100 * 101 * @return whether the move succeeded. 102 */ 103 boolean moveToNext(); 104 105 /** 106 * Move the cursor to the previous row. 107 * 108 * <p>This method will return false if the cursor is already before the 109 * first entry in the result set. 110 * 111 * @return whether the move succeeded. 112 */ 113 boolean moveToPrevious(); 114 115 /** 116 * Returns whether the cursor is pointing to the first row. 117 * 118 * @return whether the cursor is pointing at the first entry. 119 */ 120 boolean isFirst(); 121 122 /** 123 * Returns whether the cursor is pointing to the last row. 124 * 125 * @return whether the cursor is pointing at the last entry. 126 */ 127 boolean isLast(); 128 129 /** 130 * Returns whether the cursor is pointing to the position before the first 131 * row. 132 * 133 * @return whether the cursor is before the first result. 134 */ 135 boolean isBeforeFirst(); 136 137 /** 138 * Returns whether the cursor is pointing to the position after the last 139 * row. 140 * 141 * @return whether the cursor is after the last result. 142 */ 143 boolean isAfterLast(); 144 145 /** 146 * Removes the row at the current cursor position from the underlying data 147 * store. After this method returns the cursor will be pointing to the row 148 * after the row that is deleted. This has the side effect of decrementing 149 * the result of count() by one. 150 * <p> 151 * The query must have the row ID column in its selection, otherwise this 152 * call will fail. 153 * 154 * @hide 155 * @return whether the record was successfully deleted. 156 * @deprecated use {@link ContentResolver#delete(Uri, String, String[])} 157 */ 158 @Deprecated 159 boolean deleteRow(); 160 161 /** 162 * Returns the zero-based index for the given column name, or -1 if the column doesn't exist. 163 * If you expect the column to exist use {@link #getColumnIndexOrThrow(String)} instead, which 164 * will make the error more clear. 165 * 166 * @param columnName the name of the target column. 167 * @return the zero-based column index for the given column name, or -1 if 168 * the column name does not exist. 169 * @see #getColumnIndexOrThrow(String) 170 */ 171 int getColumnIndex(String columnName); 172 173 /** 174 * Returns the zero-based index for the given column name, or throws 175 * {@link IllegalArgumentException} if the column doesn't exist. If you're not sure if 176 * a column will exist or not use {@link #getColumnIndex(String)} and check for -1, which 177 * is more efficient than catching the exceptions. 178 * 179 * @param columnName the name of the target column. 180 * @return the zero-based column index for the given column name 181 * @see #getColumnIndex(String) 182 * @throws IllegalArgumentException if the column does not exist 183 */ 184 int getColumnIndexOrThrow(String columnName) throws IllegalArgumentException; 185 186 /** 187 * Returns the column name at the given zero-based column index. 188 * 189 * @param columnIndex the zero-based index of the target column. 190 * @return the column name for the given column index. 191 */ 192 String getColumnName(int columnIndex); 193 194 /** 195 * Returns a string array holding the names of all of the columns in the 196 * result set in the order in which they were listed in the result. 197 * 198 * @return the names of the columns returned in this query. 199 */ 200 String[] getColumnNames(); 201 202 /** 203 * Return total number of columns 204 * @return number of columns 205 */ 206 int getColumnCount(); 207 208 /** 209 * Returns the value of the requested column as a byte array. 210 * 211 * <p>If the native content of that column is not blob exception may throw 212 * 213 * @param columnIndex the zero-based index of the target column. 214 * @return the value of that column as a byte array. 215 */ 216 byte[] getBlob(int columnIndex); 217 218 /** 219 * Returns the value of the requested column as a String. 220 * 221 * <p>If the native content of that column is not text the result will be 222 * the result of passing the column value to String.valueOf(x). 223 * 224 * @param columnIndex the zero-based index of the target column. 225 * @return the value of that column as a String. 226 */ 227 String getString(int columnIndex); 228 229 /** 230 * Retrieves the requested column text and stores it in the buffer provided. 231 * If the buffer size is not sufficient, a new char buffer will be allocated 232 * and assigned to CharArrayBuffer.data 233 * @param columnIndex the zero-based index of the target column. 234 * if the target column is null, return buffer 235 * @param buffer the buffer to copy the text into. 236 */ 237 void copyStringToBuffer(int columnIndex, CharArrayBuffer buffer); 238 239 /** 240 * Returns the value of the requested column as a short. 241 * 242 * <p>If the native content of that column is not numeric the result will be 243 * the result of passing the column value to Short.valueOf(x). 244 * 245 * @param columnIndex the zero-based index of the target column. 246 * @return the value of that column as a short. 247 */ 248 short getShort(int columnIndex); 249 250 /** 251 * Returns the value of the requested column as an int. 252 * 253 * <p>If the native content of that column is not numeric the result will be 254 * the result of passing the column value to Integer.valueOf(x). 255 * 256 * @param columnIndex the zero-based index of the target column. 257 * @return the value of that column as an int. 258 */ 259 int getInt(int columnIndex); 260 261 /** 262 * Returns the value of the requested column as a long. 263 * 264 * <p>If the native content of that column is not numeric the result will be 265 * the result of passing the column value to Long.valueOf(x). 266 * 267 * @param columnIndex the zero-based index of the target column. 268 * @return the value of that column as a long. 269 */ 270 long getLong(int columnIndex); 271 272 /** 273 * Returns the value of the requested column as a float. 274 * 275 * <p>If the native content of that column is not numeric the result will be 276 * the result of passing the column value to Float.valueOf(x). 277 * 278 * @param columnIndex the zero-based index of the target column. 279 * @return the value of that column as a float. 280 */ 281 float getFloat(int columnIndex); 282 283 /** 284 * Returns the value of the requested column as a double. 285 * 286 * <p>If the native content of that column is not numeric the result will be 287 * the result of passing the column value to Double.valueOf(x). 288 * 289 * @param columnIndex the zero-based index of the target column. 290 * @return the value of that column as a double. 291 */ 292 double getDouble(int columnIndex); 293 294 /** 295 * Returns <code>true</code> if the value in the indicated column is null. 296 * 297 * @param columnIndex the zero-based index of the target column. 298 * @return whether the column value is null. 299 */ 300 boolean isNull(int columnIndex); 301 302 /** 303 * Returns <code>true</code> if the cursor supports updates. 304 * 305 * @return whether the cursor supports updates. 306 * @hide 307 * @deprecated use the {@link ContentResolver} update methods instead of the Cursor 308 * update methods 309 */ 310 @Deprecated 311 boolean supportsUpdates(); 312 313 /** 314 * Returns <code>true</code> if there are pending updates that have not yet been committed. 315 * 316 * @return <code>true</code> if there are pending updates that have not yet been committed. 317 * @hide 318 * @deprecated use the {@link ContentResolver} update methods instead of the Cursor 319 * update methods 320 */ 321 @Deprecated 322 boolean hasUpdates(); 323 324 /** 325 * Updates the value for the given column in the row the cursor is 326 * currently pointing at. Updates are not committed to the backing store 327 * until {@link #commitUpdates()} is called. 328 * 329 * @param columnIndex the zero-based index of the target column. 330 * @param value the new value. 331 * @return whether the operation succeeded. 332 * @hide 333 * @deprecated use the {@link ContentResolver} update methods instead of the Cursor 334 * update methods 335 */ 336 @Deprecated 337 boolean updateBlob(int columnIndex, byte[] value); 338 339 /** 340 * Updates the value for the given column in the row the cursor is 341 * currently pointing at. Updates are not committed to the backing store 342 * until {@link #commitUpdates()} is called. 343 * 344 * @param columnIndex the zero-based index of the target column. 345 * @param value the new value. 346 * @return whether the operation succeeded. 347 * @hide 348 * @deprecated use the {@link ContentResolver} update methods instead of the Cursor 349 * update methods 350 */ 351 @Deprecated 352 boolean updateString(int columnIndex, String value); 353 354 /** 355 * Updates the value for the given column in the row the cursor is 356 * currently pointing at. Updates are not committed to the backing store 357 * until {@link #commitUpdates()} is called. 358 * 359 * @param columnIndex the zero-based index of the target column. 360 * @param value the new value. 361 * @return whether the operation succeeded. 362 * @hide 363 * @deprecated use the {@link ContentResolver} update methods instead of the Cursor 364 * update methods 365 */ 366 @Deprecated 367 boolean updateShort(int columnIndex, short value); 368 369 /** 370 * Updates the value for the given column in the row the cursor is 371 * currently pointing at. Updates are not committed to the backing store 372 * until {@link #commitUpdates()} is called. 373 * 374 * @param columnIndex the zero-based index of the target column. 375 * @param value the new value. 376 * @return whether the operation succeeded. 377 * @hide 378 * @deprecated use the {@link ContentResolver} update methods instead of the Cursor 379 * update methods 380 */ 381 @Deprecated 382 boolean updateInt(int columnIndex, int value); 383 384 /** 385 * Updates the value for the given column in the row the cursor is 386 * currently pointing at. Updates are not committed to the backing store 387 * until {@link #commitUpdates()} is called. 388 * 389 * @param columnIndex the zero-based index of the target column. 390 * @param value the new value. 391 * @return whether the operation succeeded. 392 * @hide 393 * @deprecated use the {@link ContentResolver} update methods instead of the Cursor 394 * update methods 395 */ 396 @Deprecated 397 boolean updateLong(int columnIndex, long value); 398 399 /** 400 * Updates the value for the given column in the row the cursor is 401 * currently pointing at. Updates are not committed to the backing store 402 * until {@link #commitUpdates()} is called. 403 * 404 * @param columnIndex the zero-based index of the target column. 405 * @param value the new value. 406 * @return whether the operation succeeded. 407 * @hide 408 * @deprecated use the {@link ContentResolver} update methods instead of the Cursor 409 * update methods 410 */ 411 @Deprecated 412 boolean updateFloat(int columnIndex, float value); 413 414 /** 415 * Updates the value for the given column in the row the cursor is 416 * currently pointing at. Updates are not committed to the backing store 417 * until {@link #commitUpdates()} is called. 418 * 419 * @param columnIndex the zero-based index of the target column. 420 * @param value the new value. 421 * @return whether the operation succeeded. 422 * @hide 423 * @deprecated use the {@link ContentResolver} update methods instead of the Cursor 424 * update methods 425 */ 426 @Deprecated 427 boolean updateDouble(int columnIndex, double value); 428 429 /** 430 * Removes the value for the given column in the row the cursor is 431 * currently pointing at. Updates are not committed to the backing store 432 * until {@link #commitUpdates()} is called. 433 * 434 * @param columnIndex the zero-based index of the target column. 435 * @return whether the operation succeeded. 436 * @hide 437 * @deprecated use the {@link ContentResolver} update methods instead of the Cursor 438 * update methods 439 */ 440 @Deprecated 441 boolean updateToNull(int columnIndex); 442 443 /** 444 * Atomically commits all updates to the backing store. After completion, 445 * this method leaves the data in an inconsistent state and you should call 446 * {@link #requery} before reading data from the cursor again. 447 * 448 * @return whether the operation succeeded. 449 * @hide 450 * @deprecated use the {@link ContentResolver} update methods instead of the Cursor 451 * update methods 452 */ 453 @Deprecated 454 boolean commitUpdates(); 455 456 /** 457 * Atomically commits all updates to the backing store, as well as the 458 * updates included in values. After completion, 459 * this method leaves the data in an inconsistent state and you should call 460 * {@link #requery} before reading data from the cursor again. 461 * 462 * @param values A map from row IDs to Maps associating column names with 463 * updated values. A null value indicates the field should be 464 removed. 465 * @return whether the operation succeeded. 466 * @hide 467 * @deprecated use the {@link ContentResolver} update methods instead of the Cursor 468 * update methods 469 */ 470 @Deprecated 471 boolean commitUpdates(Map<? extends Long, 472 ? extends Map<String,Object>> values); 473 474 /** 475 * Reverts all updates made to the cursor since the last call to 476 * commitUpdates. 477 * @hide 478 * @deprecated use the {@link ContentResolver} update methods instead of the Cursor 479 * update methods 480 */ 481 @Deprecated 482 void abortUpdates(); 483 484 /** 485 * Deactivates the Cursor, making all calls on it fail until {@link #requery} is called. 486 * Inactive Cursors use fewer resources than active Cursors. 487 * Calling {@link #requery} will make the cursor active again. 488 */ 489 void deactivate(); 490 491 /** 492 * Performs the query that created the cursor again, refreshing its 493 * contents. This may be done at any time, including after a call to {@link 494 * #deactivate}. 495 * 496 * @return true if the requery succeeded, false if not, in which case the 497 * cursor becomes invalid. 498 */ 499 boolean requery(); 500 501 /** 502 * Closes the Cursor, releasing all of its resources and making it completely invalid. 503 * Unlike {@link #deactivate()} a call to {@link #requery()} will not make the Cursor valid 504 * again. 505 */ 506 void close(); 507 508 /** 509 * return true if the cursor is closed 510 * @return true if the cursor is closed. 511 */ 512 boolean isClosed(); 513 514 /** 515 * Register an observer that is called when changes happen to the content backing this cursor. 516 * Typically the data set won't change until {@link #requery()} is called. 517 * 518 * @param observer the object that gets notified when the content backing the cursor changes. 519 * @see #unregisterContentObserver(ContentObserver) 520 */ 521 void registerContentObserver(ContentObserver observer); 522 523 /** 524 * Unregister an observer that has previously been registered with this 525 * cursor via {@link #registerContentObserver}. 526 * 527 * @param observer the object to unregister. 528 * @see #registerContentObserver(ContentObserver) 529 */ 530 void unregisterContentObserver(ContentObserver observer); 531 532 /** 533 * Register an observer that is called when changes happen to the contents 534 * of the this cursors data set, for example, when the data set is changed via 535 * {@link #requery()}, {@link #deactivate()}, or {@link #close()}. 536 * 537 * @param observer the object that gets notified when the cursors data set changes. 538 * @see #unregisterDataSetObserver(DataSetObserver) 539 */ 540 void registerDataSetObserver(DataSetObserver observer); 541 542 /** 543 * Unregister an observer that has previously been registered with this 544 * cursor via {@link #registerContentObserver}. 545 * 546 * @param observer the object to unregister. 547 * @see #registerDataSetObserver(DataSetObserver) 548 */ 549 void unregisterDataSetObserver(DataSetObserver observer); 550 551 /** 552 * Register to watch a content URI for changes. This can be the URI of a specific data row (for 553 * example, "content://my_provider_type/23"), or a a generic URI for a content type. 554 * 555 * @param cr The content resolver from the caller's context. The listener attached to 556 * this resolver will be notified. 557 * @param uri The content URI to watch. 558 */ 559 void setNotificationUri(ContentResolver cr, Uri uri); 560 561 /** 562 * onMove() will only be called across processes if this method returns true. 563 * @return whether all cursor movement should result in a call to onMove(). 564 */ 565 boolean getWantsAllOnMoveCalls(); 566 567 /** 568 * Returns a bundle of extra values. This is an optional way for cursors to provide out-of-band 569 * metadata to their users. One use of this is for reporting on the progress of network requests 570 * that are required to fetch data for the cursor. 571 * 572 * <p>These values may only change when requery is called. 573 * @return cursor-defined values, or Bundle.EMTPY if there are no values. Never null. 574 */ 575 Bundle getExtras(); 576 577 /** 578 * This is an out-of-band way for the the user of a cursor to communicate with the cursor. The 579 * structure of each bundle is entirely defined by the cursor. 580 * 581 * <p>One use of this is to tell a cursor that it should retry its network request after it 582 * reported an error. 583 * @param extras extra values, or Bundle.EMTPY. Never null. 584 * @return extra values, or Bundle.EMTPY. Never null. 585 */ 586 Bundle respond(Bundle extras); 587} 588