Merge "Add some simple annotations to Cursor."

2 files changed, 63 insertions, 60 deletions

diff --git a/core/java/android/database/Cursor.java b/core/java/android/database/Cursor.java
index 2afb755031b9..afa1c209c811 100644
--- a/core/java/android/database/Cursor.java
+++ b/core/java/android/database/Cursor.java
@@ -16,6 +16,8 @@
 
 package android.database;
 
+import android.annotation.IntDef;
+import android.annotation.IntRange;
 import android.annotation.NonNull;
 import android.annotation.Nullable;
 import android.content.ContentResolver;
@@ -23,6 +25,8 @@ import android.net.Uri;
 import android.os.Bundle;
 
 import java.io.Closeable;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
 import java.util.Arrays;
 import java.util.List;
 
@@ -56,12 +60,23 @@ public interface Cursor extends Closeable {
     /** Value returned by {@link #getType(int)} if the specified column type is blob */
     static final int FIELD_TYPE_BLOB = 4;
 
+    /** @hide */
+    @IntDef(prefix = { "FIELD_TYPE_" }, value = {
+            FIELD_TYPE_NULL,
+            FIELD_TYPE_INTEGER,
+            FIELD_TYPE_FLOAT,
+            FIELD_TYPE_STRING,
+            FIELD_TYPE_BLOB,
+    })
+    @Retention(RetentionPolicy.SOURCE)
+    public @interface FieldType {}
+
     /**
      * Returns the numbers of rows in the cursor.
      *
      * @return the number of rows in the cursor.
      */
-    int getCount();
+    @IntRange(from = 0) int getCount();
 
     /**
      * Returns the current position of the cursor in the row set.
@@ -72,7 +87,7 @@ public interface Cursor extends Closeable {
      *
      * @return the current cursor position.
      */
-    int getPosition();
+    @IntRange(from = -1) int getPosition();
 
     /**
      * Move the cursor by a relative amount, forward or backward, from the
@@ -101,7 +116,7 @@ public interface Cursor extends Closeable {
      * @param position the zero-based position to move to.
      * @return whether the requested move fully succeeded.
      */
-    boolean moveToPosition(int position);
+    boolean moveToPosition(@IntRange(from = -1) int position);
 
     /**
      * Move the cursor to the first row.
@@ -181,7 +196,7 @@ public interface Cursor extends Closeable {
      * the column name does not exist.
      * @see #getColumnIndexOrThrow(String)
      */
-    int getColumnIndex(String columnName);
+    @IntRange(from = -1) int getColumnIndex(String columnName);
 
     /**
      * Returns the zero-based index for the given column name, or throws
@@ -194,7 +209,8 @@ public interface Cursor extends Closeable {
      * @see #getColumnIndex(String)
      * @throws IllegalArgumentException if the column does not exist
      */
-    int getColumnIndexOrThrow(String columnName) throws IllegalArgumentException;
+    @IntRange(from = 0) int getColumnIndexOrThrow(String columnName)
+            throws IllegalArgumentException;
 
     /**
      * Returns the column name at the given zero-based column index.
@@ -202,7 +218,7 @@ public interface Cursor extends Closeable {
      * @param columnIndex the zero-based index of the target column.
      * @return the column name for the given column index.
      */
-    String getColumnName(int columnIndex);
+    String getColumnName(@IntRange(from = 0) int columnIndex);
 
     /**
      * Returns a string array holding the names of all of the columns in the
@@ -216,7 +232,7 @@ public interface Cursor extends Closeable {
      * Return total number of columns
      * @return number of columns 
      */
-    int getColumnCount();
+    @IntRange(from = 0) int getColumnCount();
     
     /**
      * Returns the value of the requested column as a byte array.
@@ -228,7 +244,7 @@ public interface Cursor extends Closeable {
      * @param columnIndex the zero-based index of the target column.
      * @return the value of that column as a byte array.
      */
-    byte[] getBlob(int columnIndex);
+    byte[] getBlob(@IntRange(from = 0) int columnIndex);
 
     /**
      * Returns the value of the requested column as a String.
@@ -240,7 +256,7 @@ public interface Cursor extends Closeable {
      * @param columnIndex the zero-based index of the target column.
      * @return the value of that column as a String.
      */
-    String getString(int columnIndex);
+    String getString(@IntRange(from = 0) int columnIndex);
     
     /**
      * Retrieves the requested column text and stores it in the buffer provided.
@@ -250,7 +266,7 @@ public interface Cursor extends Closeable {
      *        if the target column is null, return buffer
      * @param buffer the buffer to copy the text into. 
      */
-    void copyStringToBuffer(int columnIndex, CharArrayBuffer buffer);
+    void copyStringToBuffer(@IntRange(from = 0) int columnIndex, CharArrayBuffer buffer);
     
     /**
      * Returns the value of the requested column as a short.
@@ -263,7 +279,7 @@ public interface Cursor extends Closeable {
      * @param columnIndex the zero-based index of the target column.
      * @return the value of that column as a short.
      */
-    short getShort(int columnIndex);
+    short getShort(@IntRange(from = 0) int columnIndex);
 
     /**
      * Returns the value of the requested column as an int.
@@ -276,7 +292,7 @@ public interface Cursor extends Closeable {
      * @param columnIndex the zero-based index of the target column.
      * @return the value of that column as an int.
      */
-    int getInt(int columnIndex);
+    int getInt(@IntRange(from = 0) int columnIndex);
 
     /**
      * Returns the value of the requested column as a long.
@@ -289,7 +305,7 @@ public interface Cursor extends Closeable {
      * @param columnIndex the zero-based index of the target column.
      * @return the value of that column as a long.
      */
-    long getLong(int columnIndex);
+    long getLong(@IntRange(from = 0) int columnIndex);
 
     /**
      * Returns the value of the requested column as a float.
@@ -302,7 +318,7 @@ public interface Cursor extends Closeable {
      * @param columnIndex the zero-based index of the target column.
      * @return the value of that column as a float.
      */
-    float getFloat(int columnIndex);
+    float getFloat(@IntRange(from = 0) int columnIndex);
 
     /**
      * Returns the value of the requested column as a double.
@@ -315,28 +331,18 @@ public interface Cursor extends Closeable {
      * @param columnIndex the zero-based index of the target column.
      * @return the value of that column as a double.
      */
-    double getDouble(int columnIndex);
+    double getDouble(@IntRange(from = 0) int columnIndex);
 
     /**
      * Returns data type of the given column's value.
      * The preferred type of the column is returned but the data may be converted to other types
      * as documented in the get-type methods such as {@link #getInt(int)}, {@link #getFloat(int)}
      * etc.
-     *<p>
-     * Returned column types are
-     * <ul>
-     *   <li>{@link #FIELD_TYPE_NULL}</li>
-     *   <li>{@link #FIELD_TYPE_INTEGER}</li>
-     *   <li>{@link #FIELD_TYPE_FLOAT}</li>
-     *   <li>{@link #FIELD_TYPE_STRING}</li>
-     *   <li>{@link #FIELD_TYPE_BLOB}</li>
-     *</ul>
-     *</p>
      *
      * @param columnIndex the zero-based index of the target column.
      * @return column value type
      */
-    int getType(int columnIndex);
+    @FieldType int getType(@IntRange(from = 0) int columnIndex);
 
     /**
      * Returns <code>true</code> if the value in the indicated column is null.
@@ -344,7 +350,7 @@ public interface Cursor extends Closeable {
      * @param columnIndex the zero-based index of the target column.
      * @return whether the column value is null.
      */
-    boolean isNull(int columnIndex);
+    boolean isNull(@IntRange(from = 0) int columnIndex);
 
     /**
      * Deactivates the Cursor, making all calls on it fail until {@link #requery} is called.
diff --git a/core/java/android/database/CursorWindow.java b/core/java/android/database/CursorWindow.java
index 063a2d00a306..ac0593869d5a 100644
--- a/core/java/android/database/CursorWindow.java
+++ b/core/java/android/database/CursorWindow.java
@@ -17,6 +17,7 @@
 package android.database;
 
 import android.annotation.BytesLong;
+import android.annotation.IntRange;
 import android.compat.annotation.UnsupportedAppUsage;
 import android.content.res.Resources;
 import android.database.sqlite.SQLiteClosable;
@@ -230,7 +231,7 @@ public class CursorWindow extends SQLiteClosable implements Parcelable {
      *
      * @return The zero-based start position.
      */
-    public int getStartPosition() {
+    public @IntRange(from = 0) int getStartPosition() {
         return mStartPos;
     }
 
@@ -243,7 +244,7 @@ public class CursorWindow extends SQLiteClosable implements Parcelable {
      *
      * @param pos The new zero-based start position.
      */
-    public void setStartPosition(int pos) {
+    public void setStartPosition(@IntRange(from = 0) int pos) {
         mStartPos = pos;
     }
 
@@ -252,7 +253,7 @@ public class CursorWindow extends SQLiteClosable implements Parcelable {
      *
      * @return The number of rows in this cursor window.
      */
-    public int getNumRows() {
+    public @IntRange(from = 0) int getNumRows() {
         acquireReference();
         try {
             return nativeGetNumRows(mWindowPtr);
@@ -272,7 +273,7 @@ public class CursorWindow extends SQLiteClosable implements Parcelable {
      * @param columnNum The new number of columns.
      * @return True if successful.
      */
-    public boolean setNumColumns(int columnNum) {
+    public boolean setNumColumns(@IntRange(from = 0) int columnNum) {
         acquireReference();
         try {
             return nativeSetNumColumns(mWindowPtr, columnNum);
@@ -317,7 +318,7 @@ public class CursorWindow extends SQLiteClosable implements Parcelable {
      * @deprecated Use {@link #getType(int, int)} instead.
      */
     @Deprecated
-    public boolean isNull(int row, int column) {
+    public boolean isNull(@IntRange(from = 0) int row, @IntRange(from = 0) int column) {
         return getType(row, column) == Cursor.FIELD_TYPE_NULL;
     }
 
@@ -332,7 +333,7 @@ public class CursorWindow extends SQLiteClosable implements Parcelable {
      * @deprecated Use {@link #getType(int, int)} instead.
      */
     @Deprecated
-    public boolean isBlob(int row, int column) {
+    public boolean isBlob(@IntRange(from = 0) int row, @IntRange(from = 0) int column) {
         int type = getType(row, column);
         return type == Cursor.FIELD_TYPE_BLOB || type == Cursor.FIELD_TYPE_NULL;
     }
@@ -347,7 +348,7 @@ public class CursorWindow extends SQLiteClosable implements Parcelable {
      * @deprecated Use {@link #getType(int, int)} instead.
      */
     @Deprecated
-    public boolean isLong(int row, int column) {
+    public boolean isLong(@IntRange(from = 0) int row, @IntRange(from = 0) int column) {
         return getType(row, column) == Cursor.FIELD_TYPE_INTEGER;
     }
 
@@ -361,7 +362,7 @@ public class CursorWindow extends SQLiteClosable implements Parcelable {
      * @deprecated Use {@link #getType(int, int)} instead.
      */
     @Deprecated
-    public boolean isFloat(int row, int column) {
+    public boolean isFloat(@IntRange(from = 0) int row, @IntRange(from = 0) int column) {
         return getType(row, column) == Cursor.FIELD_TYPE_FLOAT;
     }
 
@@ -376,29 +377,20 @@ public class CursorWindow extends SQLiteClosable implements Parcelable {
      * @deprecated Use {@link #getType(int, int)} instead.
      */
     @Deprecated
-    public boolean isString(int row, int column) {
+    public boolean isString(@IntRange(from = 0) int row, @IntRange(from = 0) int column) {
         int type = getType(row, column);
         return type == Cursor.FIELD_TYPE_STRING || type == Cursor.FIELD_TYPE_NULL;
     }
 
     /**
      * Returns the type of the field at the specified row and column index.
-     * <p>
-     * The returned field types are:
-     * <ul>
-     * <li>{@link Cursor#FIELD_TYPE_NULL}</li>
-     * <li>{@link Cursor#FIELD_TYPE_INTEGER}</li>
-     * <li>{@link Cursor#FIELD_TYPE_FLOAT}</li>
-     * <li>{@link Cursor#FIELD_TYPE_STRING}</li>
-     * <li>{@link Cursor#FIELD_TYPE_BLOB}</li>
-     * </ul>
-     * </p>
      *
      * @param row The zero-based row index.
      * @param column The zero-based column index.
      * @return The field type.
      */
-    public int getType(int row, int column) {
+    public @Cursor.FieldType int getType(@IntRange(from = 0) int row,
+            @IntRange(from = 0) int column) {
         acquireReference();
         try {
             return nativeGetType(mWindowPtr, row - mStartPos, column);
@@ -428,7 +420,7 @@ public class CursorWindow extends SQLiteClosable implements Parcelable {
      * @param column The zero-based column index.
      * @return The value of the field as a byte array.
      */
-    public byte[] getBlob(int row, int column) {
+    public byte[] getBlob(@IntRange(from = 0) int row, @IntRange(from = 0) int column) {
         acquireReference();
         try {
             return nativeGetBlob(mWindowPtr, row - mStartPos, column);
@@ -463,7 +455,7 @@ public class CursorWindow extends SQLiteClosable implements Parcelable {
      * @param column The zero-based column index.
      * @return The value of the field as a string.
      */
-    public String getString(int row, int column) {
+    public String getString(@IntRange(from = 0) int row, @IntRange(from = 0) int column) {
         acquireReference();
         try {
             return nativeGetString(mWindowPtr, row - mStartPos, column);
@@ -502,7 +494,8 @@ public class CursorWindow extends SQLiteClosable implements Parcelable {
      * @param buffer The {@link CharArrayBuffer} to hold the string.  It is automatically
      * resized if the requested string is larger than the buffer's current capacity.
       */
-    public void copyStringToBuffer(int row, int column, CharArrayBuffer buffer) {
+    public void copyStringToBuffer(@IntRange(from = 0) int row, @IntRange(from = 0) int column,
+            CharArrayBuffer buffer) {
         if (buffer == null) {
             throw new IllegalArgumentException("CharArrayBuffer should not be null");
         }
@@ -536,7 +529,7 @@ public class CursorWindow extends SQLiteClosable implements Parcelable {
      * @param column The zero-based column index.
      * @return The value of the field as a <code>long</code>.
      */
-    public long getLong(int row, int column) {
+    public long getLong(@IntRange(from = 0) int row, @IntRange(from = 0) int column) {
         acquireReference();
         try {
             return nativeGetLong(mWindowPtr, row - mStartPos, column);
@@ -568,7 +561,7 @@ public class CursorWindow extends SQLiteClosable implements Parcelable {
      * @param column The zero-based column index.
      * @return The value of the field as a <code>double</code>.
      */
-    public double getDouble(int row, int column) {
+    public double getDouble(@IntRange(from = 0) int row, @IntRange(from = 0) int column) {
         acquireReference();
         try {
             return nativeGetDouble(mWindowPtr, row - mStartPos, column);
@@ -589,7 +582,7 @@ public class CursorWindow extends SQLiteClosable implements Parcelable {
      * @param column The zero-based column index.
      * @return The value of the field as a <code>short</code>.
      */
-    public short getShort(int row, int column) {
+    public short getShort(@IntRange(from = 0) int row, @IntRange(from = 0) int column) {
         return (short) getLong(row, column);
     }
 
@@ -605,7 +598,7 @@ public class CursorWindow extends SQLiteClosable implements Parcelable {
      * @param column The zero-based column index.
      * @return The value of the field as an <code>int</code>.
      */
-    public int getInt(int row, int column) {
+    public int getInt(@IntRange(from = 0) int row, @IntRange(from = 0) int column) {
         return (int) getLong(row, column);
     }
 
@@ -621,7 +614,7 @@ public class CursorWindow extends SQLiteClosable implements Parcelable {
      * @param column The zero-based column index.
      * @return The value of the field as an <code>float</code>.
      */
-    public float getFloat(int row, int column) {
+    public float getFloat(@IntRange(from = 0) int row, @IntRange(from = 0) int column) {
         return (float) getDouble(row, column);
     }
 
@@ -633,7 +626,8 @@ public class CursorWindow extends SQLiteClosable implements Parcelable {
      * @param column The zero-based column index.
      * @return True if successful.
      */
-    public boolean putBlob(byte[] value, int row, int column) {
+    public boolean putBlob(byte[] value,
+            @IntRange(from = 0) int row, @IntRange(from = 0) int column) {
         acquireReference();
         try {
             return nativePutBlob(mWindowPtr, value, row - mStartPos, column);
@@ -650,7 +644,8 @@ public class CursorWindow extends SQLiteClosable implements Parcelable {
      * @param column The zero-based column index.
      * @return True if successful.
      */
-    public boolean putString(String value, int row, int column) {
+    public boolean putString(String value,
+            @IntRange(from = 0) int row, @IntRange(from = 0) int column) {
         acquireReference();
         try {
             return nativePutString(mWindowPtr, value, row - mStartPos, column);
@@ -667,7 +662,8 @@ public class CursorWindow extends SQLiteClosable implements Parcelable {
      * @param column The zero-based column index.
      * @return True if successful.
      */
-    public boolean putLong(long value, int row, int column) {
+    public boolean putLong(long value,
+            @IntRange(from = 0) int row, @IntRange(from = 0) int column) {
         acquireReference();
         try {
             return nativePutLong(mWindowPtr, value, row - mStartPos, column);
@@ -685,7 +681,8 @@ public class CursorWindow extends SQLiteClosable implements Parcelable {
      * @param column The zero-based column index.
      * @return True if successful.
      */
-    public boolean putDouble(double value, int row, int column) {
+    public boolean putDouble(double value,
+            @IntRange(from = 0) int row, @IntRange(from = 0) int column) {
         acquireReference();
         try {
             return nativePutDouble(mWindowPtr, value, row - mStartPos, column);
@@ -701,7 +698,7 @@ public class CursorWindow extends SQLiteClosable implements Parcelable {
      * @param column The zero-based column index.
      * @return True if successful.
      */
-    public boolean putNull(int row, int column) {
+    public boolean putNull(@IntRange(from = 0) int row, @IntRange(from = 0) int column) {
         acquireReference();
         try {
             return nativePutNull(mWindowPtr, row - mStartPos, column);