From 65068b099e0f54bea44a353751a2654991e2df29 Mon Sep 17 00:00:00 2001 From: Daniel Trebbien Date: Sun, 31 Oct 2010 12:19:07 -0700 Subject: Clarify documentation of Cursor get* methods. Make clear in the Javadoc comments of the `Cursor` get* methods that implementations thereof can have implementation-defined behavior. In some cases, these changes actually correct the documentation. For example, in the case of `getShort` and the `SQLiteCursor` implementation thereof, non-numeric data is *not* converted to a `short` via Short#valueOf or even in a functionally- equivalent manner. Change-Id: Ib2f81811a603680b52fc482eb9c0f3195447566f --- core/java/android/database/Cursor.java | 48 ++++++++++++++++++++++------------ 1 file changed, 32 insertions(+), 16 deletions(-) (limited to 'core') diff --git a/core/java/android/database/Cursor.java b/core/java/android/database/Cursor.java index 6539156..e339a63 100644 --- a/core/java/android/database/Cursor.java +++ b/core/java/android/database/Cursor.java @@ -211,7 +211,9 @@ public interface Cursor { /** * Returns the value of the requested column as a byte array. * - *

If the native content of that column is not blob exception may throw + *

The result and whether this method throws an exception when the + * column value is null or the column type is not a blob type is + * implementation-defined. * * @param columnIndex the zero-based index of the target column. * @return the value of that column as a byte array. @@ -221,8 +223,9 @@ public interface Cursor { /** * Returns the value of the requested column as a String. * - *

If the native content of that column is not text the result will be - * the result of passing the column value to String.valueOf(x). + *

The result and whether this method throws an exception when the + * column value is null or the column type is not a string type is + * implementation-defined. * * @param columnIndex the zero-based index of the target column. * @return the value of that column as a String. @@ -242,8 +245,10 @@ public interface Cursor { /** * Returns the value of the requested column as a short. * - *

If the native content of that column is not numeric the result will be - * the result of passing the column value to Short.valueOf(x). + *

The result and whether this method throws an exception when the + * column value is null, the column type is not an integral type, or the + * integer value is outside the range [Short.MIN_VALUE, + * Short.MAX_VALUE] is implementation-defined. * * @param columnIndex the zero-based index of the target column. * @return the value of that column as a short. @@ -253,8 +258,10 @@ public interface Cursor { /** * Returns the value of the requested column as an int. * - *

If the native content of that column is not numeric the result will be - * the result of passing the column value to Integer.valueOf(x). + *

The result and whether this method throws an exception when the + * column value is null, the column type is not an integral type, or the + * integer value is outside the range [Integer.MIN_VALUE, + * Integer.MAX_VALUE] is implementation-defined. * * @param columnIndex the zero-based index of the target column. * @return the value of that column as an int. @@ -264,8 +271,10 @@ public interface Cursor { /** * Returns the value of the requested column as a long. * - *

If the native content of that column is not numeric the result will be - * the result of passing the column value to Long.valueOf(x). + *

The result and whether this method throws an exception when the + * column value is null, the column type is not an integral type, or the + * integer value is outside the range [Long.MIN_VALUE, + * Long.MAX_VALUE] is implementation-defined. * * @param columnIndex the zero-based index of the target column. * @return the value of that column as a long. @@ -275,8 +284,10 @@ public interface Cursor { /** * Returns the value of the requested column as a float. * - *

If the native content of that column is not numeric the result will be - * the result of passing the column value to Float.valueOf(x). + *

The result and whether this method throws an exception when the + * column value is null, the column type is not a floating-point type, or the + * floating-point value is not representable as a float value is + * implementation-defined. * * @param columnIndex the zero-based index of the target column. * @return the value of that column as a float. @@ -286,8 +297,10 @@ public interface Cursor { /** * Returns the value of the requested column as a double. * - *

If the native content of that column is not numeric the result will be - * the result of passing the column value to Double.valueOf(x). + *

The result and whether this method throws an exception when the + * column value is null, the column type is not a floating-point type, or the + * floating-point value is not representable as a double value is + * implementation-defined. * * @param columnIndex the zero-based index of the target column. * @return the value of that column as a double. @@ -573,7 +586,8 @@ public interface Cursor { * that are required to fetch data for the cursor. * *

These values may only change when requery is called. - * @return cursor-defined values, or Bundle.EMTPY if there are no values. Never null. + * @return cursor-defined values, or {@link android.os.Bundle#EMPTY Bundle.EMPTY} if there + * are no values. Never null. */ Bundle getExtras(); @@ -583,8 +597,10 @@ public interface Cursor { * *

One use of this is to tell a cursor that it should retry its network request after it * reported an error. - * @param extras extra values, or Bundle.EMTPY. Never null. - * @return extra values, or Bundle.EMTPY. Never null. + * @param extras extra values, or {@link android.os.Bundle#EMPTY Bundle.EMPTY}. + * Never null. + * @return extra values, or {@link android.os.Bundle#EMPTY Bundle.EMPTY}. + * Never null. */ Bundle respond(Bundle extras); } -- cgit v1.1