Cursor-API

官网：https://developer.android.google.cn/reference/android/database/Cursor

光标

科特林 |爪哇

public interface Cursor 
implements Closeable

android.database.Cursor

已知间接子类

抽象电流, 文摘窗口, 交叉过程电流, 交叉过程CursorWrapper, CursorWrapper, MatrixCursor, 默格柯萨, 莫克柯莎, SQLiteCursor

 

---

此接口提供对数据库查询返回的结果集的随机读写访问。

游标实现不需要同步，因此使用来自多个线程的游标的代码在使用游标时应该执行自己的同步。

实现应该子类AbstractCursor.

 

摘要

常数
int	FIELD_TYPE_BLOB 返回值getType(int)如果指定的列类型为BLOB
int	FIELD_TYPE_FLOAT 返回值getType(int)如果指定的列类型是浮动的
int	FIELD_TYPE_INTEGER 返回值getType(int)如果指定的列类型为整数
int	FIELD_TYPE_NULL 返回值getType(int)如果指定的列为空
int	FIELD_TYPE_STRING 返回值getType(int)如果指定的列类型为字符串

公共方法
abstract void	close() 关闭游标，释放其所有资源并使其完全无效。
abstract void	copyStringToBuffer(int columnIndex, CharArrayBuffer buffer) 检索请求的列文本并将其存储在提供的缓冲区中。
abstract void	deactivate() 此方法在API级别16中被废弃。requery()是不受欢迎的，这个也是。
abstract byte[]	getBlob(int columnIndex) 将请求列的值作为字节数组返回。
abstract int	getColumnCount() 返回列总数
abstract int	getColumnIndex(String columnName) 返回给定列名的基于零的索引，如果该列不存在，则返回-1。
abstract int	getColumnIndexOrThrow(String columnName) 返回给定列名的基于零的索引，或引发IllegalArgumentException如果列不存在。
abstract String	getColumnName(int columnIndex) 返回给定的基于零的列索引处的列名。
abstract String[]	getColumnNames() 返回一个字符串数组，该数组按结果中列出的所有列的顺序保存结果集中所有列的名称。
abstract int	getCount() 返回光标中的行数。
abstract double	getDouble(int columnIndex) 将请求列的值作为Double返回。
abstract Bundle	getExtras() 返回多个附加值。
abstract float	getFloat(int columnIndex) 将请求列的值作为浮动返回。
abstract int	getInt(int columnIndex) 将请求列的值作为int返回。
abstract long	getLong(int columnIndex) 将请求列的值作为Long返回。
abstract Uri	getNotificationUri() 返回将传递此游标数据更改通知的URI，正如先前由setNotificationUri(ContentResolver, Uri).
default List<Uri>	getNotificationUris() 返回此游标数据更改通知将在其中传递的URI，如先前由setNotificationUris(ContentResolver, List).
abstract int	getPosition() 返回光标在行集中的当前位置。
abstract short	getShort(int columnIndex) 将请求列的值作为简短返回。
abstract String	getString(int columnIndex) 将请求列的值作为字符串返回。
abstract int	getType(int columnIndex) 返回给定列的值的数据类型。
abstract boolean	getWantsAllOnMoveCalls() 只有当此方法返回true时，onMove()才会跨进程调用。
abstract boolean	isAfterLast() 返回光标是否指向最后一行之后的位置。
abstract boolean	isBeforeFirst() 返回光标是否指向第一行之前的位置。
abstract boolean	isClosed() 如果游标关闭，则返回true
abstract boolean	isFirst() 返回光标是否指向第一行。
abstract boolean	isLast() 返回光标是否指向最后一行。
abstract boolean	isNull(int columnIndex) 回报true如果指定列中的值为NULL。
abstract boolean	move(int offset) 将光标从当前位置向前或向后移动一个相对数量。
abstract boolean	moveToFirst() 将光标移动到第一行。
abstract boolean	moveToLast() 将光标移到最后一行。
abstract boolean	moveToNext() 将光标移动到下一行。
abstract boolean	moveToPosition(int position) 将光标移动到绝对位置。
abstract boolean	moveToPrevious() 将光标移动到上一行。
abstract void	registerContentObserver(ContentObserver observer) 注册当支持此游标的内容发生更改时调用的观察者。
abstract void	registerDataSetObserver(DataSetObserver observer) 注册当此游标数据集的内容发生更改时调用的观察者，例如，当数据集通过requery(), deactivate()，或close().
abstract boolean	requery() 此方法在API级别15中被废弃。请不要使用此方法。只需请求一个新的游标，这样您就可以异步完成此操作，并在新游标返回后更新您的列表视图。
abstract Bundle	respond(Bundle extras) 这是游标用户与光标通信的一种带外方式。
abstract void	setExtras(Bundle extras) 设置Bundle将由getExtras().
abstract void	setNotificationUri(ContentResolver cr, Uri uri) 注册以查看更改的内容URI。
default void	setNotificationUris(ContentResolver cr, List<Uri> uris) 类似于setNotificationUri(android.content.ContentResolver, android.net.Uri)，但此版本允许查看多个内容URI以进行更改。
abstract void	unregisterContentObserver(ContentObserver observer) 注销以前在此游标中注册的观察者。registerContentObserver(ContentObserver).
abstract void	unregisterDataSetObserver(DataSetObserver observer) 注销以前在此游标中注册的观察者。registerContentObserver(ContentObserver).

遗传方法

从接口 java.io.Closeable

从接口 java.lang.AutoCloseable

常数

场型水滴

加进空气污染指数第11级

public static final int FIELD_TYPE_BLOB

返回值getType(int)如果指定的列类型为BLOB

 

常数：4(0x00000004)

场式浮子

加进空气污染指数第11级

public static final int FIELD_TYPE_FLOAT

返回值getType(int)如果指定的列类型是浮动的

 

常数：2(0x00000002)

字段型整数

加进空气污染指数第11级

public static final int FIELD_TYPE_INTEGER

返回值getType(int)如果指定的列类型为整数

 

常数：1(0x00000001)

字段型空

加进空气污染指数第11级

public static final int FIELD_TYPE_NULL

返回值getType(int)如果指定的列为空

 

常数：0(0x00000000)

字段型字符串

加进空气污染指数第11级

public static final int FIELD_TYPE_STRING

返回值getType(int)如果指定的列类型为字符串

 

常数：3(0x00000003)

公共方法

关

加进API一级

public abstract void close ()

关闭游标，释放其所有资源并使其完全无效。不像deactivate()打电话给requery()将不再使光标有效。

 

CopyStringToBuffer

加进API一级

public abstract void copyStringToBuffer (int columnIndex, 
                CharArrayBuffer buffer)

检索请求的列文本并将其存储在提供的缓冲区中。如果缓冲区大小不够，将分配一个新的char缓冲区并分配给ChararrayBuffer.data

 

参数
columnIndex	int目标列的基于零的索引。如果目标列为空，则返回缓冲区。
buffer	CharArrayBuffer要将文本复制到的缓冲区。

停用

加进API一级 
不受欢迎API第16级

public abstract void deactivate ()

 

API级别16中不推荐此方法。
自requery()是不受欢迎的，这个也是。

取消游标，使其上的所有调用都失败，直到requery()叫做。非活动游标使用的资源比活动游标少。呼叫requery()将使光标再次活动。

 

盖布洛布

加进API一级

public abstract byte[] getBlob (int columnIndex)

将请求列的值作为字节数组返回。

结果以及当列值为NULL或列类型不是BLOB类型时，此方法是否引发异常都是实现定义的。

 

参数
columnIndex	int目标列的基于零的索引。

回报
byte[]	该列作为字节数组的值。

[计]哥伦布数

加进API一级

public abstract int getColumnCount ()

返回列总数

 

回报
int	栏数

getColumnIndex

加进API一级

public abstract int getColumnIndex (String columnName)

返回给定列名的基于零的索引，如果该列不存在，则返回-1。如果希望列存在，请使用getColumnIndexOrThrow(java.lang.String)相反，这将使错误更加清楚。

 

参数
columnName	String目标列的名称。

回报
int	给定列名的基于零的列索引，如果列名不存在，则为-1。

另见：

• getColumnIndexOrThrow(String)

getColumnIndexOrThrow

加进API一级

public abstract int getColumnIndexOrThrow (String columnName)

返回给定列名的基于零的索引，或引发IllegalArgumentException如果列不存在。如果您不确定某列是否存在或不使用getColumnIndex(java.lang.String)并检查-1，这比捕获异常更有效。

 

参数
columnName	String目标列的名称。

回报
int	给定列名的基于零的列索引。

抛出
IllegalArgumentException	如果列不存在

另见：

• getColumnIndex(String)

getColumnName

加进API一级

public abstract String getColumnName (int columnIndex)

返回给定的基于零的列索引处的列名。

 

参数
columnIndex	int目标列的基于零的索引。

回报
String	给定列索引的列名。

getColumnNames

加进API一级

public abstract String[] getColumnNames ()

返回一个字符串数组，该数组按结果中列出的所有列的顺序保存结果集中所有列的名称。

 

回报
String[]	此查询中返回的列的名称。

getCount

加进API一级

public abstract int getCount ()

返回光标中的行数。

 

回报
int	光标中的行数。

盖杜布尔

加进API一级

public abstract double getDouble (int columnIndex)

将请求列的值作为Double返回。

结果以及当列值为空、列类型不是浮点类型或浮点值不能表示为double值是实现定义的。

 

参数
columnIndex	int目标列的基于零的索引。

回报
double	该列的值为Double。

getExtras

加进API一级

public abstract Bundle getExtras ()

返回多个附加值。这是游标向用户提供带外元数据的可选方式.其中一种用途是报告为游标获取数据所需的网络请求的进度。

只有在调用请求时，这些值才可能更改。

 

回报
Bundle	游标定义的值，或Bundle.EMPTY如果没有价值。绝不可能null.

getFloat

加进API一级

public abstract float getFloat (int columnIndex)

将请求列的值作为浮动返回。

结果以及当列值为空、列类型不是浮点类型或浮点值不能表示为float值是实现定义的。

 

参数
columnIndex	int目标列的基于零的索引。

回报
float	该列作为浮点数的值。

getInt

加进API一级

public abstract int getInt (int columnIndex)

将请求列的值作为int返回。

结果以及当列值为空、列类型不是整型或整数值超出范围时，此方法是否引发异常[Integer.MIN_VALUE,Integer.MAX_VALUE]是实现-定义的。

 

参数
columnIndex	int目标列的基于零的索引。

回报
int	该列的值为int。

吉龙

加进API一级

public abstract long getLong (int columnIndex)

将请求列的值作为Long返回。

结果以及当列值为空、列类型不是整型或整数值超出范围时，此方法是否引发异常[Long.MIN_VALUE,Long.MAX_VALUE]是实现-定义的。

 

参数
columnIndex	int目标列的基于零的索引。

回报
long	那列的值是长的。

getNotificationURI

加进空气污染指数第19级

public abstract Uri getNotificationUri ()

返回将传递此游标数据更改通知的URI，正如先前由setNotificationUri(ContentResolver, Uri).

 

回报
Uri	返回可与ContentResolver#registerContentObserver(android.net.Uri, boolean, ContentObserver)若要了解对此游标数据的更改，请执行以下操作。如果没有设置通知URI，则可能为空。

getNotificationUris

加进空气污染指数第29级

public List<Uri> getNotificationUris ()

返回此游标数据更改通知将在其中传递的URI，如先前由setNotificationUris(ContentResolver, List).

如果没有实现这一点，这相当于调用getNotificationUri().

 

回报
List<Uri>	返回可以与ContentResolver#registerContentObserver(android.net.Uri, boolean, ContentObserver)若要了解对此游标数据的更改，请执行以下操作。如果没有设置通知URI，则可能为空。

获取位置

加进API一级

public abstract int getPosition ()

返回光标在行集中的当前位置。这个值是基于零的。当第一次返回行集时，光标将位于位置-1，位于第一行之前。在返回最后一行之后，对Next()的另一个调用将使游标在最后一个条目之后，位于count()的位置。

 

回报
int	当前光标的位置。

getShort

加进API一级

public abstract short getShort (int columnIndex)

将请求列的值作为简短返回。

结果以及当列值为空、列类型不是整型或整数值超出范围时，此方法是否引发异常[Short.MIN_VALUE,Short.MAX_VALUE]是实现-定义的。

 

参数
columnIndex	int目标列的基于零的索引。

回报
short	该列的值为短。

getString

加进API一级

public abstract String getString (int columnIndex)

将请求列的值作为字符串返回。

当列值为NULL或列类型不是字符串类型时，该方法是否引发异常的结果是实现定义的。

 

参数
columnIndex	int目标列的基于零的索引。

回报
String	该列的值为字符串。

getType

加进空气污染指数第11级

public abstract int getType (int columnIndex)

返回给定列的值的数据类型。返回列的首选类型，但数据可以转换为其他类型，如get-type方法中记录的那样。getInt(int), getFloat(int)等。

返回的列类型为

• FIELD_TYPE_NULL
• FIELD_TYPE_INTEGER
• FIELD_TYPE_FLOAT
• FIELD_TYPE_STRING
• FIELD_TYPE_BLOB

 

 

 

参数
columnIndex	int目标列的基于零的索引。

回报
int	列值类型

getWantsAllOnMoveCalls

加进API一级

public abstract boolean getWantsAllOnMoveCalls ()

只有当此方法返回true时，onMove()才会跨进程调用。

 

回报
boolean	是否所有光标的移动都会导致对onMove()的调用。

最后一次

加进API一级

public abstract boolean isAfterLast ()

返回光标是否指向最后一行之后的位置。

 

回报
boolean	光标是否在最后一个结果之后。

第一

加进API一级

public abstract boolean isBeforeFirst ()

返回光标是否指向第一行之前的位置。

 

回报
boolean	光标是否在第一个结果之前。

等闭

加进API一级

public abstract boolean isClosed ()

如果游标关闭，则返回true

 

回报
boolean	如果光标关闭，则为true。

ISFirst

加进API一级

public abstract boolean isFirst ()

返回光标是否指向第一行。

 

回报
boolean	光标是否指向第一个条目。

最后一次

加进API一级

public abstract boolean isLast ()

返回光标是否指向最后一行。

 

回报
boolean	光标是否指向最后一个条目。

isNull

加进API一级

public abstract boolean isNull (int columnIndex)

回报true如果指定列中的值为NULL。

 

参数
columnIndex	int目标列的基于零的索引。

回报
boolean	列值是否为空。

移动

加进API一级

public abstract boolean move (int offset)

将光标从当前位置向前或向后移动一个相对数量。正偏移向前移动，负偏移向后移动。如果最后一个位置超出了结果集的界限，则结果位置将被固定为-1或count()，这取决于该值分别是在集合的前端还是末尾。

如果请求的目标可达，此方法将返回true，否则将返回false。例如，如果光标当前位于结果集中的第二个条目上，并且调用了Move(-5)，则位置将固定在-1，并返回false。

 

参数
offset	int*从当前职位适用的抵消额。

回报
boolean	请求的移动是否完全成功。

MoveToFirst

加进API一级

public abstract boolean moveToFirst ()

将光标移动到第一行。

如果游标为空，此方法将返回false。

 

回报
boolean	行动是否成功。

移动到最后

加进API一级

public abstract boolean moveToLast ()

将光标移到最后一行。

如果游标为空，此方法将返回false。

 

回报
boolean	行动是否成功。

MoveToNext

加进API一级

public abstract boolean moveToNext ()

将光标移动到下一行。

如果游标已经超过结果集中的最后一个条目，此方法将返回false。

 

回报
boolean	行动是否成功。

动位

加进API一级

public abstract boolean moveToPosition (int position)

将光标移动到绝对位置。有效的值范围是-1<=位置<=计数。

如果请求目标可达，此方法将返回true，否则将返回false。

 

参数
position	int要移动到的基于零的位置。

回报
boolean	请求的移动是否完全成功。

动感

加进API一级

public abstract boolean moveToPrevious ()

将光标移动到上一行。

如果游标已经在结果集中的第一个条目之前，此方法将返回false。

 

回报
boolean	行动是否成功。

寄存器内容观察员

加进API一级

public abstract void registerContentObserver (ContentObserver observer)

注册当支持此游标的内容发生更改时调用的观察者。通常情况下，数据集直到requery()叫做。

 

参数
observer	ContentObserver：当支持游标的内容发生更改时得到通知的对象。

另见：

• unregisterContentObserver(ContentObserver)

寄存器数据设置观察者

加进API一级

public abstract void registerDataSetObserver (DataSetObserver observer)

注册当此游标数据集的内容发生更改时调用的观察者，例如，当数据集通过requery(), deactivate()，或close().

 

参数
observer	DataSetObserver当游标数据集更改时得到通知的对象。

另见：

• unregisterDataSetObserver(DataSetObserver)

请求

加进API一级 
不受欢迎空气污染指数第15级

public abstract boolean requery ()

 

API级别15中不推荐此方法。
别用这个。只需请求一个新的游标，这样您就可以异步完成此操作，并在新游标返回后更新您的列表视图。

执行再次创建游标的查询，刷新其内容。这可以在任何时候进行，包括在呼叫deactivate()。由于此方法可以在数据库上执行查询，并且可能需要一段时间，因此如果在main(UI)线程上调用该方法，可能会导致ANR。如果在主线程上执行此方法，则会打印警告。

 

回报
boolean	如果请求成功，则为true，否则为false，则光标无效。

回应

加进API一级

public abstract Bundle respond (Bundle extras)

这是游标用户与光标通信的一种带外方式。每个包的结构完全由游标定义。

其中一种方法是告诉游标在报告错误后应该重试其网络请求。

 

参数
extras	Bundle*额外价值，或Bundle.EMPTY。绝不可能null.

回报
Bundle	额外价值，或Bundle.EMPTY。绝不可能null.

SETExtras

加进API 23级

public abstract void setExtras (Bundle extras)

设置Bundle将由getExtras().

 

参数
extras	Bundle: Bundle设置或NULL设置空包。

setNotificationURI

加进API一级

public abstract void setNotificationUri (ContentResolver cr, 
                Uri uri)

注册以查看更改的内容URI。这可以是特定数据行的URI(例如，“content：//my_Provider_type/23”)，也可以是内容类型的通用URI。

调用此命令将重写以前对setNotificationUris(android.content.ContentResolver, java.util.List).

 

参数
cr	ContentResolver来自调用方上下文的内容解析器。将通知附加到此解析器的侦听器。
uri	Uri要查看的内容URI。

setNotificationUris

加进空气污染指数第29级

public void setNotificationUris (ContentResolver cr, 
                List<Uri> uris)

类似于setNotificationUri(android.content.ContentResolver, android.net.Uri)，但此版本允许查看多个内容URI以进行更改。

如果没有实现这一点，这相当于调用setNotificationUri(android.content.ContentResolver, android.net.Uri)中的第一个URIuris.

调用此命令将重写以前对setNotificationUri(android.content.ContentResolver, android.net.Uri).

 

参数
cr	ContentResolver来自调用方上下文的内容解析器。将通知附加到此解析器的侦听器。这个值绝不能是null.
uris	List要观看的内容URI。这个值绝不能是null.

非寄存器内容观察者

加进API一级

public abstract void unregisterContentObserver (ContentObserver observer)

注销以前在此游标中注册的观察者。registerContentObserver(ContentObserver).

 

参数
observer	ContentObserver要注销的对象。

另见：

• registerContentObserver(ContentObserver)

取消注册数据设置观察者

加进API一级

public abstract void unregisterDataSetObserver (DataSetObserver observer)

注销以前在此游标中注册的观察者。registerContentObserver(ContentObserver).

 

参数
observer	DataSetObserver要注销的对象。

另见：

• registerDataSetObserver(DataSetObserver)