Cursor

初识Cursor

http://www.cnblogs.com/TerryBlog/archive/2010/07/05/1771459.html

 

API：

android.database.Cursor

 

This interface provides random(随机) read-write access（访问） to the result set returned by a database query（查询）.

Cursor implementations are not required（需要） to be synchronized（同步） so code using a Cursor from multiple threads should perform（执行） its own synchronization when using the Cursor.

Implementations should subclass AbstractCursor.

 

 

示例：假设这是我们搜索到的数据 cursor 可以存在的地方总是比我们的函数多2

-1（上边界）

0（第0行）

1（第1行）

2（第二行）

count()（下边界）

           左边共有3行数据 但是

cursor 可以指定 -1 和 3(就是count())  的。

                            但是 cursor指向的 -1 和 3 是没有数据的。

 

当对 上或下边界 执行 getString(); 方法时会在该方法系统崩溃【但是不报错】重复执行此方法就会报错。？？？？——存疑

 

 

Move 相关吧：

boolean move(int offset);

Move the cursor by a relative amount, forward or backward, from the current position. Positive offsets move forwards, negative offsets move backwards. If the final position is outside of the bounds of the result set then the resultant position will be pinned to -1 or count() depending on whether the value is off the front or end of the set, respectively.

This method will return true if the requested destination was reachable, otherwise, it returns false. For example, if the cursor is at currently on the second entry in the result set and move(-5) is called, the position will be pinned at -1, and false will be returned.

Parameters:

offset the offset to be applied from the current position.

Returns:

whether the requested move fully succeeded.

 

相对于当前位置向前或向后移动 cursor ，offset 是整数就向前移动，负数就向后移动。如果得到的超过边界的指向值，从表头越界指向 -1 从表尾越界就指向表长度数（行数）。

 

boolean moveToPosition(int position);

Move the cursor to an absolute position. The valid range of values is -1 <= position <= count.

This method will return true if the request destination was reachable, otherwise, it returns false.

Parameters:

position the zero-based position to move to.

Returns:

whether the requested move fully succeeded.

 

 

boolean moveToFirst();

Move the cursor to the first row.

This method will return false if the cursor is empty.

Returns:

whether the move succeeded.

 

就是说会移动到第 0 行：关键是如果第0行是【边界】就会把报错。

一个小实验：

{   

      Cursor cursor_1 = sqlDB_1.rawQueryWithFactory(null,sql_1, selectionArgs,"bussness_card", null);

           System.out.println("最初的位置"+cursor_1.getPosition());

           if (!cursor_1.moveToFirst())

           {

                 System.out.println("报错了");

           }

           System.out.println("现在的位置"+cursor_1.getPosition());

}   

前因：我故意查询到一个空表

后果：

最初的位置：-1   【如果表非空这个最初的位置是 也是 -1 】

报错了

现在的位置是 0

 

【就是说它是先移到 第0行 后判断这一行有没有数据的。】

 

 

boolean moveToLast();

Move the cursor to the last row.

This method will return false if the cursor is empty.

Returns:

whether the move succeeded.

 

移动到 count()-1  行

猜测和 moveToFirst()  的特性是一样的，但是没有测试。

 

boolean moveToNext();

Move the cursor to the next row.

This method will return false if the cursor is already past the last entry（记录） in the result set.

Returns:

whether the move succeeded.

 

如果刚过去的这一个是 count()行 就会报错【即：试图向下超过下边界就会报错】——然而试验结果并没有报错啊

试验：

     

                 cursor_1.moveToLast();

                 cursor_1.moveToNext();

                 cursor_1.moveToNext();

                 cursor_1.moveToNext();

                 cursor_1.moveToNext();

 

我这么做都是没有报错的。——【存疑】

 

 

boolean moveToPrevious();

Move the cursor to the previous row.

This method will return false if the cursor is already before the first entry in the result set.

Returns:

whether the move succeeded.

 

如果刚过去的这一个是 -1 行 就会报错【即：试图向上超过上边界就会报错】

试验：

     

                 cursor_1.moveToFirst();

                 System.out.println("moveToFirst之后是"+cursor_1.getPosition());

                 cursor_1.moveToPrevious();

                 cursor_1.moveToPrevious();

                 cursor_1.moveToPrevious();

                 cursor_1.moveToPrevious();

结果 同  boolean moveToNext();   【存疑】

 

 

 

 

 

get 相关

int getCount();

Returns the numbers of rows in the cursor.

Returns:

the number of rows in the cursor.

 

返回数据的行数

 

int getPosition();

Returns the current position of the cursor in the row set. The value is zero-based. When the row set is first returned the cursor will be at positon -1, which is before the first row. After the last row is returned another call to next() will leave the cursor past the last entry, at a position of count().

Returns:

the current cursor position.【返回光标当前的位置】

 

返回游标在数据集中当前的位置。这个值是以零为基础的。

When the first returned the cursor wil be at position -1,which is before the first row.【有种不翻译比翻译更好的感觉啊】

当到达数据的最后一行之后时再调用 next() 就会导致 cursor 超出最后一条记录 停留在 count() 记录上。

【这句话和 moveToNext() 中的是实验结果一致。】

 

int getColumnIndex(String columnName);

Returns the zero-based index for the given column name, or -1 if the column doesn't exist. If you expect（预期，期望） the column to exist usegetColumnIndexOrThrow(String) instead（代替）, which will make the error more clear.

Parameters:

columnName the name of the target column.

Returns:

the zero-based column index for the given column name, or -1 if the column name does not exist.

See Also:

getColumnIndexOrThrow(String)

 

为给定的列名返回以零为基础的索引，如果不存在这个列就返回 -1 。如果 你认为这个列是存在的(但返回-1)，用getColumnIndexOrThrow(String) 这个方法代替int getColumnIndex(String columnName); 会是错误更清晰。

【返回值】

以零为基础的给定列名的索引，如果你给定的列名不存在，就会返回 -1 。

 

int getColumnIndexOrThrow(String columnName)

Returns the zero-based index for the given column name, or throws IllegalArgumentException if the column doesn't exist. If you're not sure if a column will exist（存在） or not usegetColumnIndex(String) and check for -1, which is more efficient than catching the exceptions.

Parameters:

columnName the name of the target column.

Returns:

the zero-based column index for the given column name

Throws:

IllegalArgumentException - if the column does not exist

See Also:

getColumnIndex(String)

 

 

 

String getColumnName(int columnIndex);

 

 

String[] getColumnNames();

 

 

int getColumnCount();

 

 

byte[] getBlob(int columnIndex);——————blob 【二进制】

Returns the value of the requested（请求） column as a byte array.

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.

Parameters:

columnIndex the zero-based index of the target column.

Returns:

the value of that column as a byte array.

 

把指定的列作为 byte[] 返回 当 value is null 或者 这 Value 不能转化为 byte[] 类型时报错【就是拆不了箱唄】

【这个Value is null 大概就是 边界吧（至少边界报错了），，，

我试试 null 错不错事实是就是边界  null注意  可不是字符串null  经过试验  是不出错的】

试验：

Id

name

phone

1

张三

(null)【非字符串】

byte[] bytes = cursor_1.getBlob(2);

System.out.println(bytes);————java.lang.NullPointerException

=========================================================================================

总结    ：把指定的列作为 byte[] 返回 当cursor在边界或者 这 Value 不能转化为 byte[] 类型时报错

 

 

String getString(int columnIndex);

Returns the value of the requested（请求） column as a String.

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.

Parameters:

columnIndex the zero-based index of the target column.

Returns:

the value of that column as a String.

 

把请求的列的值作为 String 返回。当所请求的列是 null 的时候或者这列的数据不能转换成 String 就会报错。

当对 上或下边界 执行 getString(); 方法时会在该方法系统崩溃【但是不报错】重复执行此方法就会报错。？？？？——存疑

 

 

void copyStringToBuffer(int columnIndex, CharArrayBuffer buffer);

Retrieves（检索） the requested column text and stores（存储） it in the buffer provided. If the buffer size is not sufficient, a new char buffer will be allocated（分配） and assigned to CharArrayBuffer.data

【一个新的字符缓冲区会被分配到相应的CharArrayBuffer.data】

Parameters:

columnIndex the zero-based index of the target column. if the target column is null, return buffer

buffer the buffer to copy the text into.

 

 

 

short getShort(int columnIndex);

Returns the value of the requested column as a short.

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.

Parameters:

columnIndex the zero-based index of the target column.

Returns:

the value of that column as a short.

 

把所请求的列的值转化为 short 类型给返回；

Throw exception 的情况：【根据以上的试验 value is nall 是说 cursor 指定边界的时候】

1、cursor 指向边界  

2、Value 的类型不是 int 类型  或  这个int 类型的值超过 了 short 的范围

【is implementation-defined.       说的 大概就是 不允许转换吧————存疑】

 

 

int getInt(int columnIndex);

 

 

long getLong(int columnIndex);

 

 

float getFloat(int columnIndex);

 

 

double getDouble(int columnIndex);

 

 

int getType(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 asgetInt(int), getFloat(int) etc.

Returned column types are

·         FIELD_TYPE_NULL

·         FIELD_TYPE_INTEGER

·         FIELD_TYPE_FLOAT

·         FIELD_TYPE_STRING

·         FIELD_TYPE_BLOB ——————【BLOB 二进制】

Parameters:

columnIndex the zero-based index of the target column.

Returns:

column value type

 

 

 

boolean isNull(int columnIndex);

 

 

Uri getNotificationUri();

 

 

boolean getWantsAllOnMoveCalls();

 

 

Bundle getExtras();

Returns a bundle of extra values. This is an optional way for cursors to provide out-of-band metadata to their users. One use of this is for reporting on the progress of network requests that are required to fetch data for the cursor.

These values may only change when requery is called.

Returns:

cursor-defined values, or Bundle.EMPTY if there are no values. Nevernull.

 

 

 

 

 

is 相关

boolean isFirst();

Returns whether the cursor is pointing to the first row.

Returns:

whether the cursor is pointing at the first entry.

 

 

 

boolean isLast();

 

 

boolean isBeforeFirst();

 

 

boolean isAfterLast();

 

 

boolean isNull(int columnIndex);

Returns true if the value in the indicated column is null.

Parameters:

columnIndex the zero-based index of the target column.

Returns:

whether the column value is null.

 

 

 

boolean isClosed();

return true if the cursor is closed

Returns:

true if the cursor is closed.

 

 

 

 

 

Other Method

void setNotificationUri(ContentResolver cr, Uri uri);————Notification 【通知】

Register to watch a content URI for changes. This can be the URI of a specific data row (for example, "content://my_provider_type/23"), or a a generic URI for a content type.

Parameters:

cr The content resolver from the caller's context. The listener attached to this resolver will be notified.

uri The content URI to watch.

 

 

 

Bundle respond(Bundle extras);

This is an out-of-band way for the the user of a cursor to communicate with the cursor. The structure of each bundle is entirely defined by the cursor.

One use of this is to tell a cursor that it should retry its network request after it reported an error.

Parameters:

extras extra values, or Bundle.EMPTY. Nevernull.

Returns:

extra values, or Bundle.EMPTY. Nevernull.

 

 

 

void copyStringToBuffer(int columnIndex, CharArrayBuffer buffer);

 

 

 

 

 

转载

使用过 SQLite 数据库的童鞋对 Cursor 应该不陌生，如果你是搞.net 开发你大可以把Cursor理解成 Ado.net 中的数据集合相当于dataReader。今天特地将它单独拿出来谈，加深自己和大家对Android 中使用 Cursor 的理解。

关于 Cursor

在你理解和使用Android Cursor 的时候你必须先知道关于 Cursor 的几件事情：

·        Cursor是每行的集合。

·        使用 moveToFirst()定位第一行。

·        你必须知道每一列的名称。

·        你必须知道每一列的数据类型。

·        Cursor是一个随机的数据源。

·        所有的数据都是通过下标取得。

关于 Cursor 的重要方法：

·        close() 
关闭游标，释放资源

·        copyStringToBuffer(int columnIndex, CharArrayBuffer buffer) 
在缓冲区中检索请求的列的文本，将将其存储

·        getColumnCount() 
返回所有列的总数

·        getColumnIndex(String columnName) 
返回指定列的名称，如果不存在返回-1

·        getColumnIndexOrThrow(String columnName) 
从零开始返回指定列名称，如果不存在将抛出IllegalArgumentException 异常。

·        getColumnName(int columnIndex) 
从给定的索引返回列名

·        getColumnNames() 
返回一个字符串数组的列名

·        getCount() 
返回Cursor中的行数

·        moveToFirst() 
移动光标到第一行

·        moveToLast() 
移动光标到最后一行

·        moveToNext() 
移动光标到下一行

·        moveToPosition(int position) 
移动光标到一个绝对的位置

·        moveToPrevious() 
移动光标到上一行

下面来看看一小段代码：

 

if (cur.moveToFirst() == false)
{
//为空的Cursor

return;
}

 

访问 Cursor 的下标获得其中的数据

 

int nameColumnIndex = cur.getColumnIndex(People.NAME);
String name = cur.getString(nameColumnIndex);

 

 

现在让我们看看如何循环Cursor 取出我们需要的数据

 

while(cur.moveToNext())
{
//光标移动成功
//把数据取出
}

 

 

当cur.moveToNext()为假时将跳出循环，即 Cursor 数据循环完毕。

如果你喜欢用 for 循环而不想用While 循环可以使用Google 提供的几下方法：

·        isBeforeFirst() 
返回游标是否指向之前第一行的位置

·        isAfterLast() 
返回游标是否指向第最后一行的位置

·        isClosed() 
如果返回 true 即表示该游戏标己关闭

有了以上的方法，可以如此取出数据

 

for(cur.moveToFirst();!cur.isAfterLast();cur.moveToNext())
{
    int nameColumn = cur.getColumnIndex(People.NAME);
    int phoneColumn = cur.getColumnIndex(People.NUMBER);
    String name = cur.getString(nameColumn);
    String phoneNumber = cur.getString(phoneColumn);
}

 

Tip:在Android 查询数据是通过Cursor类来实现的。当我们使用 SQLiteDatabase.query()方法时，就会得到Cursor对象， Cursor所指向的就是每一条数据。结合ADO.net 的知识可能好理解一点。

Cursor 位于 android.database.Cursor类，可见出它的设计是基于数据库服务产生的。

另外，还有几个己知的子类，分别为：

·        AbstractCursor

·        AbstractWindowedCursor

·         CrossProcessCursor

·         CursorWrapper

·         MatrixCursor

·         MergeCursor

·         MockCursor

·        SQLiteCursor