Cursor.java revision 7cd51efcbd2d083bf577696591ef1769034f7e2f
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 * Returns the zero-based index for the given column name, or -1 if the column doesn't exist. 150 * If you expect the column to exist use {@link #getColumnIndexOrThrow(String)} instead, which 151 * will make the error more clear. 152 * 153 * @param columnName the name of the target column. 154 * @return the zero-based column index for the given column name, or -1 if 155 * the column name does not exist. 156 * @see #getColumnIndexOrThrow(String) 157 */ 158 int getColumnIndex(String columnName); 159 160 /** 161 * Returns the zero-based index for the given column name, or throws 162 * {@link IllegalArgumentException} if the column doesn't exist. If you're not sure if 163 * a column will exist or not use {@link #getColumnIndex(String)} and check for -1, which 164 * is more efficient than catching the exceptions. 165 * 166 * @param columnName the name of the target column. 167 * @return the zero-based column index for the given column name 168 * @see #getColumnIndex(String) 169 * @throws IllegalArgumentException if the column does not exist 170 */ 171 int getColumnIndexOrThrow(String columnName) throws IllegalArgumentException; 172 173 /** 174 * Returns the column name at the given zero-based column index. 175 * 176 * @param columnIndex the zero-based index of the target column. 177 * @return the column name for the given column index. 178 */ 179 String getColumnName(int columnIndex); 180 181 /** 182 * Returns a string array holding the names of all of the columns in the 183 * result set in the order in which they were listed in the result. 184 * 185 * @return the names of the columns returned in this query. 186 */ 187 String[] getColumnNames(); 188 189 /** 190 * Return total number of columns 191 * @return number of columns 192 */ 193 int getColumnCount(); 194 195 /** 196 * Returns the value of the requested column as a byte array. 197 * 198 * <p>If the native content of that column is not blob exception may throw 199 * 200 * @param columnIndex the zero-based index of the target column. 201 * @return the value of that column as a byte array. 202 */ 203 byte[] getBlob(int columnIndex); 204 205 /** 206 * Returns the value of the requested column as a String. 207 * 208 * <p>If the native content of that column is not text the result will be 209 * the result of passing the column value to String.valueOf(x). 210 * 211 * @param columnIndex the zero-based index of the target column. 212 * @return the value of that column as a String. 213 */ 214 String getString(int columnIndex); 215 216 /** 217 * Retrieves the requested column text and stores it in the buffer provided. 218 * If the buffer size is not sufficient, a new char buffer will be allocated 219 * and assigned to CharArrayBuffer.data 220 * @param columnIndex the zero-based index of the target column. 221 * if the target column is null, return buffer 222 * @param buffer the buffer to copy the text into. 223 */ 224 void copyStringToBuffer(int columnIndex, CharArrayBuffer buffer); 225 226 /** 227 * Returns the value of the requested column as a short. 228 * 229 * <p>If the native content of that column is not numeric the result will be 230 * the result of passing the column value to Short.valueOf(x). 231 * 232 * @param columnIndex the zero-based index of the target column. 233 * @return the value of that column as a short. 234 */ 235 short getShort(int columnIndex); 236 237 /** 238 * Returns the value of the requested column as an int. 239 * 240 * <p>If the native content of that column is not numeric the result will be 241 * the result of passing the column value to Integer.valueOf(x). 242 * 243 * @param columnIndex the zero-based index of the target column. 244 * @return the value of that column as an int. 245 */ 246 int getInt(int columnIndex); 247 248 /** 249 * Returns the value of the requested column as a long. 250 * 251 * <p>If the native content of that column is not numeric the result will be 252 * the result of passing the column value to Long.valueOf(x). 253 * 254 * @param columnIndex the zero-based index of the target column. 255 * @return the value of that column as a long. 256 */ 257 long getLong(int columnIndex); 258 259 /** 260 * Returns the value of the requested column as a float. 261 * 262 * <p>If the native content of that column is not numeric the result will be 263 * the result of passing the column value to Float.valueOf(x). 264 * 265 * @param columnIndex the zero-based index of the target column. 266 * @return the value of that column as a float. 267 */ 268 float getFloat(int columnIndex); 269 270 /** 271 * Returns the value of the requested column as a double. 272 * 273 * <p>If the native content of that column is not numeric the result will be 274 * the result of passing the column value to Double.valueOf(x). 275 * 276 * @param columnIndex the zero-based index of the target column. 277 * @return the value of that column as a double. 278 */ 279 double getDouble(int columnIndex); 280 281 /** 282 * Returns <code>true</code> if the value in the indicated column is null. 283 * 284 * @param columnIndex the zero-based index of the target column. 285 * @return whether the column value is null. 286 */ 287 boolean isNull(int columnIndex); 288 289 /** 290 * Deactivates the Cursor, making all calls on it fail until {@link #requery} is called. 291 * Inactive Cursors use fewer resources than active Cursors. 292 * Calling {@link #requery} will make the cursor active again. 293 */ 294 void deactivate(); 295 296 /** 297 * Performs the query that created the cursor again, refreshing its 298 * contents. This may be done at any time, including after a call to {@link 299 * #deactivate}. 300 * 301 * Since this method could execute a query on the database and potentially take 302 * a while, it could cause ANR if it is called on Main (UI) thread. 303 * A warning is printed if this method is being executed on Main thread. 304 * 305 * @return true if the requery succeeded, false if not, in which case the 306 * cursor becomes invalid. 307 */ 308 boolean requery(); 309 310 /** 311 * Closes the Cursor, releasing all of its resources and making it completely invalid. 312 * Unlike {@link #deactivate()} a call to {@link #requery()} will not make the Cursor valid 313 * again. 314 */ 315 void close(); 316 317 /** 318 * return true if the cursor is closed 319 * @return true if the cursor is closed. 320 */ 321 boolean isClosed(); 322 323 /** 324 * Register an observer that is called when changes happen to the content backing this cursor. 325 * Typically the data set won't change until {@link #requery()} is called. 326 * 327 * @param observer the object that gets notified when the content backing the cursor changes. 328 * @see #unregisterContentObserver(ContentObserver) 329 */ 330 void registerContentObserver(ContentObserver observer); 331 332 /** 333 * Unregister an observer that has previously been registered with this 334 * cursor via {@link #registerContentObserver}. 335 * 336 * @param observer the object to unregister. 337 * @see #registerContentObserver(ContentObserver) 338 */ 339 void unregisterContentObserver(ContentObserver observer); 340 341 /** 342 * Register an observer that is called when changes happen to the contents 343 * of the this cursors data set, for example, when the data set is changed via 344 * {@link #requery()}, {@link #deactivate()}, or {@link #close()}. 345 * 346 * @param observer the object that gets notified when the cursors data set changes. 347 * @see #unregisterDataSetObserver(DataSetObserver) 348 */ 349 void registerDataSetObserver(DataSetObserver observer); 350 351 /** 352 * Unregister an observer that has previously been registered with this 353 * cursor via {@link #registerContentObserver}. 354 * 355 * @param observer the object to unregister. 356 * @see #registerDataSetObserver(DataSetObserver) 357 */ 358 void unregisterDataSetObserver(DataSetObserver observer); 359 360 /** 361 * Register to watch a content URI for changes. This can be the URI of a specific data row (for 362 * example, "content://my_provider_type/23"), or a a generic URI for a content type. 363 * 364 * @param cr The content resolver from the caller's context. The listener attached to 365 * this resolver will be notified. 366 * @param uri The content URI to watch. 367 */ 368 void setNotificationUri(ContentResolver cr, Uri uri); 369 370 /** 371 * onMove() will only be called across processes if this method returns true. 372 * @return whether all cursor movement should result in a call to onMove(). 373 */ 374 boolean getWantsAllOnMoveCalls(); 375 376 /** 377 * Returns a bundle of extra values. This is an optional way for cursors to provide out-of-band 378 * metadata to their users. One use of this is for reporting on the progress of network requests 379 * that are required to fetch data for the cursor. 380 * 381 * <p>These values may only change when requery is called. 382 * @return cursor-defined values, or Bundle.EMTPY if there are no values. Never null. 383 */ 384 Bundle getExtras(); 385 386 /** 387 * This is an out-of-band way for the the user of a cursor to communicate with the cursor. The 388 * structure of each bundle is entirely defined by the cursor. 389 * 390 * <p>One use of this is to tell a cursor that it should retry its network request after it 391 * reported an error. 392 * @param extras extra values, or Bundle.EMTPY. Never null. 393 * @return extra values, or Bundle.EMTPY. Never null. 394 */ 395 Bundle respond(Bundle extras); 396} 397