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