鸿蒙OS RdbStore

RdbStore

public interface RdbStore

提供管理关系数据库 (RDB) 的方法。

此类提供用于创建、查询、更新和删除 RDB 的方法。

嵌套类摘要

修饰符和类型	接口	描述
static class	RdbStore.ConflictResolution	表示解决冲突的方法的类型。

字段摘要

修饰符和类型	字段	描述
static int	MAX_BATCH_INSERT_SIZE

方法总结

修饰符和类型	方法	描述
void	addAttach(String alias, String name, byte[] encryptKey)	附加数据库。
boolean	backup(String destName)	以指定名称备份数据库。
boolean	backup(String destName, byte[] destEncryptKey)	使用指定的加密密钥以指定名称备份数据库。
ListLong	batchInsertOrThrowException(String tableName, ListValuesBucket initialValues, RdbStore.ConflictResolution conflictResolution)	根据冲突处理策略将数据批量插入数据库。
void	beginTransaction()	以 EXCLUSIVE 模式开始事务。
void	beginTransactionWithObserver(TransactionObserver transactionObserver)	使用侦听器以独占模式开始事务。
Statement	buildStatement(String sql)	将 SQL 语句编译成可重用的语句。
void	changeEncryptKey(byte[] newEncryptKey)	更改打开的加密数据库的加密密钥。
boolean	checkIntegrity()	检查主数据库和附加数据库的完整性。
void	close()	关闭一个 RDB。
void	configLocale(Locale locale)	设置数据库区域设置。
long	count(String tableName, String whereClause, String[] whereArgs)	查询RDB存储中满足指定条件的行数。
long	count(AbsRdbPredicates absRdbPredicates)	获取数据满足 AbsRdbPredicates 的指定实例对象的行数。
int	delete(AbsRdbPredicates absRdbPredicates)	根据 AbsRdbPredicates 的指定实例对象从数据库中删除数据。
void	endTransaction()	结束交易。
void	executeSql(String sql)	执行不返回值的 SQL 语句。
void	executeSql(String sql, Object[] sqlArgs)	执行包含指定参数但不返回值的 SQL 语句。
String	getPath()	获取数据库文件的路径。
int	getVersion()	获取数据库版本。
void	giveConnectionTemporarily(long milliseconds)	暂时断开与数据库的连接以允许其他线程使用数据库。
long	insert(String table, ValuesBucket initialValues)	在目标表中插入一行数据。
long	insertOrThrowException(String table, ValuesBucket initialValues)	在目标表中插入一行数据。
long	insertWithConflictResolution(String table, ValuesBucket initialValues, RdbStore.ConflictResolution conflictResolution)	在目标表中插入一行数据并指定解决冲突的方法。
boolean	isHoldingConnection()	检查此线程是否拥有数据库连接。
boolean	isInTransaction()	检查当前线程是否正在进行事务。
boolean	isMemoryRdb()	检查数据库是否在内存中打开。
boolean	isOpen()	检查数据库是否打开。
boolean	isReadOnly()	检查数据库是否以只读模式打开。
ListPairString,String	listAttached()	查询附加数据库列表。
void	markAsCommit()	将当前事务标记为提交。
ResultSet	query(AbsRdbPredicates absRdbPredicates, String[] columns)	根据指定条件查询数据库中的数据。
ResultSet	queryByStep(AbsRdbPredicates absRdbPredicates, String[] columns)	根据指定条件查询数据库中的数据。
ResultSet	querySql(String sql, String[] sqlArgs)	执行一条 SQL 语句。
ResultSet	querySqlByStep(String sql, String[] sqlArgs)	执行 SQL 语句并指定结果集。
ResultSet	querySqlWithHook(String sql, String[] sqlArgs, ResultSetHook resultSetHook)	执行 SQL 语句并指定结果集。
ResultSet	queryWithHook(AbsRdbPredicates absRdbPredicates, String[] columns, ResultSetHook resultSetHook)	根据指定条件查询数据库中的数据并指定结果集。
long	replace(String table, ValuesBucket initialValues)	替换目标表中的一行数据。
long	replaceOrThrowException(String table, ValuesBucket initialValues)	替换目标表中的一行数据。
boolean	restore(String srcName)	从指定的未加密数据库文件恢复数据库。
boolean	restore(String srcName, byte[] srcEncryptKey, byte[] destEncryptKey)	从指定的加密或未加密数据库文件恢复数据库。
void	setVersion(int version)	设置新数据库的版本。
String	toString()	获取数据库存储的描述。
int	update(ValuesBucket values, AbsRdbPredicates absRdbPredicates)	根据 AbsRdbPredicates 的指定实例对象更新数据库中的数据。
int	updateWithConflictResolution(ValuesBucket values, AbsRdbPredicates absRdbPredicates, RdbStore.ConflictResolution conflictResolution)	更新目标表中的一行数据，并指定解决冲突的方法。

字段详细信息

MAX_BATCH_INSERT_SIZE

static final int MAX_BATCH_INSERT_SIZE

方法详情

insert

long insert(String table, ValuesBucket initialValues)

在目标表中插入一行数据。

参数：

参数名称	参数描述
table	表示目标表。
initialValues	表示要插入到表中的数据行。 数据包含存储在 ValuesBucket 中的键值对。 键值对与表的列名相关联。

返回:

如果操作成功，则返回行 ID； 否则返回 -1。

insertOrThrowException

long insertOrThrowException(String table, ValuesBucket initialValues)

在目标表中插入一行数据。

参数：

参数名称	参数描述
table	表示目标表。
initialValues	表示要插入到表中的数据行。 数据包含存储在 ValuesBucket 中的键值对。 键值对与表的列名相关联。

返回:

如果操作成功，则返回行 ID； 否则返回 -1。

Throws:

Throw名称	Throw描述
RdbException	如果发生 SQLite 数据库错误，则引发此异常。 您必须自己处理此异常。

batchInsertOrThrowException

ListLong batchInsertOrThrowException(String tableName, ListValuesBucket initialValues, RdbStore.ConflictResolution conflictResolution)

根据冲突处理策略将数据批量插入数据库。

如果冲突处理策略为空，将使用默认策略 ConflictResolution#ON_CONFLICT_NONE。 如果在数据插入过程中发生异常，操作会因冲突处理策略的类型而异。

• ConflictResolution#ON_CONFLICT_ROLLBACK：如果发生数据冲突，数据库列为空，或者数据库列只有一个值，所有插入的数据将被回滚。
• ConflictResolution#ON_CONFLICT_ABORT or ConflictResolution#ON_CONFLICT_FAIL：如果发生数据冲突，数据库列为空，或者数据库列只有一个值，插入的数据将被保留，并抛出异常。
• ConflictResolution#ON_CONFLICT_IGNORE：如果发生数据冲突或数据库列为空，将忽略异常，返回值-1。数据插入将继续，直到所有数据都插入数据库。如果外键不存在或发生外键冲突，请参阅 ConflictResolution#ON_CONFLICT_ABORT。
• ConflictResolution#ON_CONFLICT_REPLACE：如果发生数据冲突，或者数据库列有默认值或只有一个值，将替换冲突数据并继续插入数据，直到所有数据都插入数据库。如果数据库列没有默认值或发生外键冲突，请参阅 ConflictResolution#ON_CONFLICT_ABORT。

参数:

参数名称	参数描述
tableName	表示数据库的表名。
initialValues	表示要插入数据库的数据。
conflictResolution	表示冲突处理策略。

返回:

如果批量插入成功，则返回所有行的 ID。 如果使用 ConflictResolution#ON_CONFLICT_IGNORE 策略，则返回的列表可能包含 -1。

Throws:

Throw名称	Throw描述
IllegalArgumentException	如果表名为 null 或空字符串、initialValues 为 null 或空列表、initialValues 中的值为 null 或空字符串，或者 initialValues 中的值数量超过 RdbStore#MAX_BATCH_INSERT_SIZE，则抛出此异常。
RdbException	如果数据插入数据库失败，则抛出此异常。

replace

long replace(String table, ValuesBucket initialValues)

替换目标表中的一行数据。

如果目标行不存在，则此方法插入一行。

参数：

参数名称	参数描述
table	表示目标表。
initialValues	表示用于替换目标表中的数据行的数据行。 数据包含存储在 ValuesBucket 中的键值对。 键值对与表的列名相关联。

返回:

如果操作成功，则返回行 ID； 否则返回 -1。

replaceOrThrowException

long replaceOrThrowException(String table, ValuesBucket initialValues)

替换目标表中的一行数据。

如果目标行不存在，则此方法插入一行。

参数：

参数名称	参数描述
table	表示目标表。
initialValues	表示用于替换目标表中的数据行的数据行。 数据包含存储在 ValuesBucket 中的键值对。 键值对与表的列名相关联。

返回:

如果操作成功，则返回行 ID； 否则返回 -1。

Throws:

Throw名称	Throw描述
RdbException	如果发生 SQLite 数据库错误，则引发此异常。 您必须自己处理此异常。

insertWithConflictResolution

long insertWithConflictResolution(String table, ValuesBucket initialValues, RdbStore.ConflictResolution conflictResolution)

在目标表中插入一行数据并指定解决冲突的方法。

参数：

参数名称	参数描述
table	表示目标表。
initialValues	表示要插入到表中的数据行。 数据包含存储在 ValuesBucket 中的键值对。 键值对与表的列名相关联。
conflictResolution	表示解决冲突的方法。

返回:

如果操作成功，则返回行 ID； 否则返回 -1。

delete

int delete(AbsRdbPredicates absRdbPredicates)

根据 AbsRdbPredicates 的指定实例对象从数据库中删除数据。

您可以传递 AbsRdbPredicates 的实例对象，例如 RdbPredicates 和 RawRdbPredicates 来指定删除条件。 如果传入 RdbPredicates 对象，可以调用 RdbPredicates#equalTo 等方法设置删除条件。 如果传递 RawRdbPredicates 对象，则只能设置数据库 tableName、whereClause 和 whereArgs。 whereArgs 是 whereClause 中占位符的值，必须与占位符的顺序相同。

参数：

参数名称	参数描述
absRdbPredicates	指示 AbsRdbPredicates 的实例对象指定的删除条件。

返回:

返回受影响的行数。

update

int update(ValuesBucket values, AbsRdbPredicates absRdbPredicates)

根据 AbsRdbPredicates 的指定实例对象更新数据库中的数据。

您可以传递RdbPredicates 和RawRdbPredicates 等AbsRdbPredicates 的实例对象来指定更新条件。 如果传递 RdbPredicates 对象，则可以调用 RdbPredicates#equalTo 等方法设置更新条件。 如果传递 RawRdbPredicates 对象，则只能设置数据库 tableName、whereClause 和 whereArgs。 whereArgs 是 whereClause 中占位符的值，必须与占位符的顺序相同。

参数：

参数名称	参数描述
values	表示数据库中要更新的数据行。 数据包含存储在 ValuesBucket 中的键值对。 键值对与数据库表的列名相关联。
absRdbPredicates	通过 AbsRdbPredicates 的实例对象指示指定的更新条件。

返回:

返回受影响的行数。

updateWithConflictResolution

int updateWithConflictResolution(ValuesBucket values, AbsRdbPredicates absRdbPredicates, RdbStore.ConflictResolution conflictResolution)

更新目标表中的一行数据，并指定解决冲突的方法。

参数：

参数名称	参数描述
values	表示要插入到表中的数据行。 数据包含存储在 ValuesBucket 中的键值对。 键值对与表的列名相关联。
absRdbPredicates	通过 RdbPredicates 的实例对象指示指定的更新条件。
conflictResolution	表示解决冲突的方法。

返回:

返回受影响的行数。

query

ResultSet query(AbsRdbPredicates absRdbPredicates, String[] columns)

根据指定条件查询数据库中的数据。

参数：

参数名称	参数描述
absRdbPredicates	表示查询条件。
columns	表示要查询的列。 如果值为 null，则查询适用于所有列。

返回:

如果操作成功，则返回一个 ResultSet 对象；

queryWithHook

ResultSet queryWithHook(AbsRdbPredicates absRdbPredicates, String[] columns, ResultSetHook resultSetHook)

根据指定条件查询数据库中的数据并指定结果集。

参数：

参数名称	参数描述
absRdbPredicates	表示查询条件。
resultSetHook	指示要使用的结果集工厂。
columns	表示要查询的列。 如果值为 null，则查询适用于所有列。

返回:

如果操作成功，则返回一个 ResultSet 对象；

querySql

ResultSet querySql(String sql, String[] sqlArgs)

执行一条 SQL 语句。

参数：

参数名称	参数描述
sql	指示要执行的 SQL 语句。
sqlArgs	表示SQL语句中的参数值。 值是字符串。

返回:

如果操作成功，则返回一个 ResultSet 对象；

querySqlWithHook

ResultSet querySqlWithHook(String sql, String[] sqlArgs, ResultSetHook resultSetHook)

执行 SQL 语句并指定结果集。

参数：

参数名称	参数描述
resultSetHook	指示要使用的结果集工厂。
sql	指示要执行的 SQL 语句。
sqlArgs	表示SQL语句中的参数值。 值是字符串。

返回:

如果操作成功，则返回一个 ResultSet 对象；

queryByStep

ResultSet queryByStep(AbsRdbPredicates absRdbPredicates, String[] columns)

根据指定条件查询数据库中的数据。

参数：

参数名称	参数描述
absRdbPredicates	表示查询条件。
columns	表示要查询的列。 如果值为 null，则查询适用于所有列。

返回:

如果操作成功，则返回一个 ResultSet 对象

querySqlByStep

ResultSet querySqlByStep(String sql, String[] sqlArgs)

执行 SQL 语句并指定结果集。

参数：

参数名称	参数描述
sql	指示要执行的 SQL 语句。
sqlArgs	表示SQL语句中的参数值。 值是字符串。

返回:

如果操作成功，则返回一个 ResultSet 对象；

executeSql

void executeSql(String sql)

执行不返回值的 SQL 语句。

不要使用这种方法通过“PRAGMA journal_mode'value'”语句来改变数据库连接的journal_mode。

参数：

参数名称	参数描述
sql	指示要执行的 SQL 语句。

Throws:

Throw名称	Throw描述
RdbException	如果 SQL 语句无效，则引发此异常。 您必须自己处理此异常。

executeSql

void executeSql(String sql, Object[] sqlArgs)

执行包含指定参数但不返回值的 SQL 语句。

不要使用这种方法通过“PRAGMA journal_mode'value'”语句来改变数据库连接的journal_mode。

参数：

参数名称	参数描述
sql	指示要执行的 SQL 语句。
sqlArgs	表示SQL语句中的参数值。 值是字符串。

Throws:

Throw名称	Throw描述
RdbException	如果 SQL 语句无效，则引发此异常。 您必须自己处理此异常。

buildStatement

Statement buildStatement(String sql)

将 SQL 语句编译成可重用的语句。

一个语句不能被两个线程同时使用。

参数：

参数名称	参数描述
sql	指示要编译的 SQL 语句。

返回:

返回一个 Statement 对象，它表示一个预编译的 SQL 语句。

count

long count(String tableName, String whereClause, String[] whereArgs)

查询RDB存储中满足指定条件的行数。

要获得可执行的SQL查询语句，将表名和条件子句连接成字符串select count(*) from tableName whereClause，并将字符串中的问号(?)替换为whereArgs中的值。 这样就可以调用Statement#executeAndGetLong执行SQL查询语句，获取满足指定条件的行数。 如果 whereClause 为 null 或为空，则返回表中的总行数。

参数：

参数名称	参数描述
tableName	表示数据库表的名称。 如果为 null 或为空，则抛出 IllegalArgumentException。
whereClause	表示一个可选的条件子句，例如 id =? 和 name like？，其中id和name是数据库表的列。
whereArgs	指示包含用于替换 whereClause 中问号 (?) 的值的数组。

返回:

返回 RDB 存储中满足指定条件的行数。

count

long count(AbsRdbPredicates absRdbPredicates)

获取数据满足 AbsRdbPredicates 的指定实例对象的行数。

参数：

参数名称	参数描述
absRdbPredicates	表示 AbsRdbPredicates 的实例对象指定的计数条件。

返回:

返回数据满足 AbsRdbPredicates 的指定实例对象的行数。

addAttach

void addAttach(String alias, String name, byte[] encryptKey)

附加数据库。

参数：

参数名称	参数描述
alias	指示要附加的数据库的别名。
name	指示要附加的数据库的名称。
encryptKey	指示用于加密要附加的数据库的密钥。

Throws:

Throw名称	Throw描述
IllegalArgumentException	如果别名为 null，则引发此异常。

listAttached

ListPairString,String listAttached()

查询附加数据库列表。

返回:

返回附加数据库的列表，包括它们的名称和路径。 主数据库也包含在列表中。

changeEncryptKey

void changeEncryptKey(byte[] newEncryptKey)

更改打开的加密数据库的加密密钥。

此方法仅适用于加密数据库，不能用于将其更改为未加密数据库。 在调用此方法之前，请确保数据库已打开并且没有事务正在使用数据库连接。

参数：

参数名称	参数描述
newEncryptKey	表示数据库的新加密密钥。

Throws:

Throw名称	Throw描述
IllegalArgumentException	如果新的加密密钥为 null 或空字符串，则引发此异常。
IllegalStateException	如果数据库未打开或未加密，或者事务正在使用数据库连接，则引发此异常。
RdbException	如果更改加密数据库的加密密钥失败，则抛出此异常。

getVersion

int getVersion()

获取数据库版本。

返回:

返回数据库版本。

setVersion

void setVersion(int version)

设置新数据库的版本。

参数：

参数名称	参数描述
version	指示要设置的数据库版本。

beginTransaction

void beginTransaction()

以 EXCLUSIVE 模式开始事务。

endTransaction() 方法用于结束事务。 如果在事务结束时没有使用 markAsCommit() 方法将事务标记为已提交，则所有更改都会回滚。

beginTransactionWithObserver

void beginTransactionWithObserver(TransactionObserver transactionObserver)

使用侦听器以独占模式开始事务。

endTransaction() 方法用于结束事务。 如果在事务结束时没有使用 markAsCommit() 方法将事务标记为已提交，则所有更改都会回滚。

参数：

参数名称	参数描述
transactionObserver	提供可以在事务启动、提交或回滚时调用的回调方法。

markAsCommit

void markAsCommit()

将当前事务标记为提交。

调用该方法后，在调用 endTransaction() 方法之前不要进行任何操作。 无论是否发生错误，事务都将被提交。

endTransaction

void endTransaction()

结束事务。

isInTransaction

boolean isInTransaction()

检查当前线程是否正在进行事务。

返回:

如果当前线程正在进行事务，则返回 true； 否则返回 false。

giveConnectionTemporarily

void giveConnectionTemporarily(long milliseconds)

暂时断开与数据库的连接以允许其他线程使用数据库。

该方法可用于提交当前事务并暂时断开与数据库的连接，以便其他线程可以使用数据库。 在指定的时间段后，将开始新的交易。 使用此方法时，请确保当前事务已启动，并且该事务未使用 markAsCommit() 方法标记为已提交； 否则，调用此方法将失败。 在调用此方法之前所做的任何更改都无法回滚。

参数：

参数名称	参数描述
milliseconds	指示当前连接从数据库中断的持续时间（毫秒）。

Throws:

Throw名称	Throw描述
IllegalStateException	如果当前线程不包含事务或包含嵌套事务，或者在调用此方法之前已使用 markAsCommit() 方法将事务标记为已提交，则抛出此异常。

isHoldingConnection

boolean isHoldingConnection()

检查此线程是否拥有数据库连接。

返回:

如果此线程拥有数据库连接，则返回 true； 否则返回 false。

isOpen

boolean isOpen()

检查数据库是否打开。

返回:

如果数据库已打开，则返回 true； 否则返回 false。

getPath

String getPath()

获取数据库文件的路径。

返回:

返回数据库文件的路径。

isReadOnly

boolean isReadOnly()

检查数据库是否以只读模式打开。

返回:

如果数据库以只读模式打开，则返回 true； 否则返回 false。

isMemoryRdb

boolean isMemoryRdb()

检查数据库是否在内存中打开。

返回:

如果数据库在内存中打开，则返回 true； 否则返回 false。

checkIntegrity

boolean checkIntegrity()

检查主数据库和附加数据库的完整性。

此方法调用 SQLite 数据库的完整性检查命令。

返回:

如果数据库是完整的，则返回 true； 否则返回 false。

close

void close()

关闭一个 RDB。

不能再使用封闭的 RDB。

backup

boolean backup(String destName)

以指定名称备份数据库。

生成的备份文件未加密。

参数：

参数名称	参数描述
destName	表示保存数据库备份的名称。 确保您的应用程序对该名称具有写入权限。

返回:

如果数据库备份成功返回true； 否则返回 false。

restore

boolean restore(String srcName)

从指定的未加密数据库文件恢复数据库。

调用该方法时，会删除原始数据并生成未加密的数据库。

参数：

参数名称	参数描述
srcName	表示保存未加密数据库文件的名称。 确保您的应用程序对该名称具有写入权限。

返回:

如果数据库恢复成功，则返回 true； 否则返回 false。

backup

boolean backup(String destName, byte[] destEncryptKey)

使用指定的加密密钥以指定名称备份数据库。

生成的备份已加密。 如果 destEncryptKey 为 null，则生成的备份未加密。 在这种情况下，此方法等效于 RdbStore#backup(String) 方法。

参数：

参数名称	参数描述
destName	表示保存数据库备份的名称。 确保您的应用程序对该名称具有写入权限。
destEncryptKey	指示要备份的数据库的加密密钥。 它可以与当前数据库的不同。

返回:

如果数据库备份成功返回true； 否则返回 false。

restore

boolean restore(String srcName, byte[] srcEncryptKey, byte[] destEncryptKey)

从指定的加密或未加密数据库文件恢复数据库。

当被调用时，此方法会删除原始数据并生成一个加密或未加密的数据库，由您的应用程序定义。 如果 srcEncryptKey 和 destEncryptKey 都为 null，则此方法等效于 RdbStore#restore(String) 方法。

参数：

参数名称	参数描述
srcName	表示存储源数据库文件的名称。 确保您的应用程序对该名称具有写入权限。
srcEncryptKey	表示源数据库的加密密钥。 如果数据库未加密，则将此参数的值设置为 null。
destEncryptKey	表示恢复的数据库的加密密钥。如果希望数据库不加密，则将该参数的值设置为null。

返回:

如果数据库恢复成功，则返回 true； 否则返回 false。

configLocale

void configLocale(Locale locale)

设置数据库区域设置。

如果数据库是只读的或数据集在事务中，则此方法不可用。 数据库区域设置好后，可以使用 select from table where column=xxxx COLLATE LOCALES; 或按列 COLLATE LOCALES ASC 从测试订单中选择 ； 在本地对数据进行排序和查询。

参数：

参数名称	参数描述
locale	指示要设置的语言环境。

toString

String toString()

获取数据库存储的描述。

覆盖：

类 Object 中的 toString

返回:

返回 RdbStore 的描述。