本文主要还是参考官方文档,然后以保存搜索历史为例操作一波。
准备工作
Room
在 SQLite
上提供了一个抽象层,以便在充分利用 SQLite 的强大功能的同时,能够流畅地访问数据库。
依赖
如需在应用中使用 Room
,请将以下依赖项添加到应用的 build.gradle
文件。
dependencies {
def room_version = "2.2.5"
implementation "androidx.room:room-runtime:$room_version"
kapt "androidx.room:room-compiler:$room_version"
// optional - Kotlin Extensions and Coroutines support for Room
implementation "androidx.room:room-ktx:$room_version"
// optional - Test helpers
testImplementation "androidx.room:room-testing:$room_version"
}
复制代码
主要组件
应用使用 Room 数据库来获取与该数据库关联的数据访问对象 (DAO)。然后,应用使用每个 DAO 从数据库中获取实体,然后再将对这些实体的所有更改保存回数据库中。 最后,应用使用实体来获取和设置与数据库中的表列相对应的值。
关系如图:
ok,基本概念了解之后,看一下具体是怎么搞的。
Entity
@Entity(tableName = "t_history")
data class History(
/**
* @PrimaryKey主键,autoGenerate = true 自增
* @ColumnInfo 列 ,typeAffinity 字段类型
* @Ignore 忽略
*/
@PrimaryKey(autoGenerate = true)
@ColumnInfo(name = "id", typeAffinity = ColumnInfo.INTEGER)
val id: Int? = null,
@ColumnInfo(name = "name", typeAffinity = ColumnInfo.TEXT)
val name: String?,
@ColumnInfo(name = "insert_time", typeAffinity = ColumnInfo.TEXT)
val insertTime: String?,
@ColumnInfo(name = "type", typeAffinity = ColumnInfo.INTEGER)
val type: Int = 1
)
复制代码
Entity 对象对应一张表,使用@Entity
注解,并声明你的表名即可
@PrimaryKey
主键,autoGenerate = true
自增
@ColumnInfo
列,并声明列名 ,typeAffinity
字段类型
@Ignore
声明忽略的对象
很简单的一张表,主要是name
和insertTime
字段。
DAO
@Dao
interface HistoryDao {
//按类型 查询所有搜索历史
@Query("SELECT * FROM t_history WHERE type=:type")
fun getAll(type: Int = 1): Flow<List<History>>
@ExperimentalCoroutinesApi
fun getAllDistinctUntilChanged() = getAll().distinctUntilChanged()
//添加一条搜索历史
@Insert
fun insert(history: History)
//删除一条搜索历史
@Delete
fun delete(history: History)
//更新一条搜索历史
@Update
fun update(history: History)
//根据id 删除一条搜索历史
@Query("DELETE FROM t_history WHERE id = :id")
fun deleteByID(id: Int)
//删除所有搜索历史
@Query("DELETE FROM t_history")
fun deleteAll()
}
复制代码
@Insert:增
@Delete:删
@Update:改
@Query:查
这里有一个点需要注意的,就是查询所有搜索历史
返回的集合我用Flow
修饰了。
只要是数据库中的任意一个数据有更新,无论是哪一行数据的更改,那就重新执行 query
操作并再次派发 Flow
。
同样道理,如果一个不相关的数据更新时,Flow
也会被派发,会收到与之前相同的数据。
这是因为 SQLite 数据库的内容更新通知功能是以表 (Table) 数据为单位,而不是以行 (Row) 数据为单位,因此只要是表中的数据有更新,它就触发内容更新通知。Room 不知道表中有更新的数据是哪一个,因此它会重新触发 DAO 中定义的 query 操作。您可以使用 Flow 的操作符,比如 distinctUntilChanged 来确保只有在当您关心的数据有更新时才会收到通知。
//按类型 查询所有搜索历史
@Query("SELECT * FROM t_history WHERE type=:type")
fun getAll(type: Int = 1): Flow<List<History>>
@ExperimentalCoroutinesApi
fun getAllDistinctUntilChanged() = getAll().distinctUntilChanged()
复制代码
数据库
@Database(entities = [History::class], version = 1)
abstract class HistoryDatabase : RoomDatabase() {
abstract fun historyDao(): HistoryDao
companion object {
private const val DATABASE_NAME = "history.db"
private lateinit var mPersonDatabase: HistoryDatabase
//注意:如果您的应用在单个进程中运行,在实例化 AppDatabase 对象时应遵循单例设计模式。
//每个 RoomDatabase 实例的成本相当高,而您几乎不需要在单个进程中访问多个实例
fun getInstance(context: Context): HistoryDatabase {
if (!this::mPersonDatabase.isInitialized) {
//创建的数据库的实例
mPersonDatabase = Room.databaseBuilder(
context.applicationContext,
HistoryDatabase::class.java,
DATABASE_NAME
).build()
}
return mPersonDatabase
}
}
}
复制代码
使用@Database
注解声明
entities
数组,对应此数据库中的所有表
version
数据库版本号
注意:
如果您的应用在单个进程中运行,在实例化 AppDatabase 对象时应遵循单例设计模式
。 每个 RoomDatabase 实例的成本相当高,而您几乎不需要在单个进程中访问多个实例。
使用
在需要的地方获取数据库
mHistoryDao = HistoryDatabase.getInstance(this).historyDao()
复制代码
获取搜索历史
private fun getSearchHistory() {
MainScope().launch(Dispatchers.IO) {
mHistoryDao.getAll().collect {
withContext(Dispatchers.Main){
//更新ui
}
}
}
}
复制代码
collect
是Flow
获取数据的方式,并不是唯一方式,可以查看文档。
为什么放在协程
里面呢,因为数据库的操作是费时的,而协程可以轻松的指定线程,这样不阻塞UI
线程。
查看 Flow 源码也发现,Flow 是协程包下的
package kotlinx.coroutines.flow
复制代码
以 collect 为例,也是被suspend
修饰的,既然支持挂起
,那配合协程
岂不美哉。
@InternalCoroutinesApi
public suspend fun collect(collector: FlowCollector<T>)
复制代码
保存搜索记录
private fun saveSearchHistory(text: String) {
MainScope().launch(Dispatchers.IO) {
mHistoryDao.insert(History(null, text, DateUtils.longToString(System.currentTimeMillis())))
}
}
复制代码
清空本地历史
private fun cleanHistory() {
MainScope().launch(Dispatchers.IO) {
mHistoryDao.deleteAll()
}
}
复制代码
作者:https://blog.csdn.net/yechaoa
数据库升级
数据库升级是一个重要的操作,毕竟可能会造成数据丢失,也是很严重的问题。
Room 通过Migration
类来执行升级的操作,我们只要告诉Migration
类改了什么就行,比如新增
字段或表。
定义 Migration 类
/**
* 数据库版本 1->2 t_history表格新增了updateTime列
*/
private val MIGRATION_1_2: Migration = object : Migration(1, 2) {
override fun migrate(database: SupportSQLiteDatabase) {
database.execSQL("ALTER TABLE t_history ADD COLUMN updateTime String")
}
}
/**
* 数据库版本 2->3 新增label表
*/
private val MIGRATION_2_3: Migration = object : Migration(2, 3) {
override fun migrate(database: SupportSQLiteDatabase) {
database.execSQL("CREATE TABLE IF NOT EXISTS `t_label` (`id` INTEGER PRIMARY KEY autoincrement, `name` TEXT)")
}
}
复制代码
Migration
接收两个参数:
startVersion 旧版本
endVersion 新版本
通知数据库更新
mPersonDatabase = Room.databaseBuilder(
context.applicationContext,
HistoryDatabase::class.java,
DATABASE_NAME
).addMigrations(MIGRATION_1_2, MIGRATION_2_3)
.build()
复制代码
完整代码
@Database(entities = [History::class, Label::class], version = 3)
abstract class HistoryDatabase : RoomDatabase() {
abstract fun historyDao(): HistoryDao
companion object {
private const val DATABASE_NAME = "history.db"
private lateinit var mPersonDatabase: HistoryDatabase
fun getInstance(context: Context): HistoryDatabase {
if (!this::mPersonDatabase.isInitialized) {
//创建的数据库的实例
mPersonDatabase = Room.databaseBuilder(
context.applicationContext,
HistoryDatabase::class.java,
DATABASE_NAME
).addMigrations(MIGRATION_1_2, MIGRATION_2_3)
.build()
}
return mPersonDatabase
}
/**
* 数据库版本 1->2 t_history表格新增了updateTime列
*/
private val MIGRATION_1_2: Migration = object : Migration(1, 2) {
override fun migrate(database: SupportSQLiteDatabase) {
database.execSQL("ALTER TABLE t_history ADD COLUMN updateTime String")
}
}
/**
* 数据库版本 2->3 新增label表
*/
private val MIGRATION_2_3: Migration = object : Migration(2, 3) {
override fun migrate(database: SupportSQLiteDatabase) {
database.execSQL("CREATE TABLE IF NOT EXISTS `t_label` (`id` INTEGER PRIMARY KEY autoincrement, `name` TEXT)")
}
}
}
}
复制代码
注意:@Database
注解中版本号的更改,如果是新增表的话,entities
参数里也要添加上。
建议升级操作顺序
修改版本号 -> 添加 Migration -> 添加给 databaseBuilder
配置编译器选项
Room 具有以下注解处理器选项:
room.schemaLocation
:配置并启用将数据库架构导出到给定目录中的 JSON 文件的功能。如需了解详情,请参阅 Room 迁移。
room.incremental
:启用 Gradle 增量注释处理器。
room.expandProjection
:配置 Room 以重写查询,使其顶部星形投影在展开后仅包含 DAO 方法返回类型中定义的列。
android {
...
defaultConfig {
...
javaCompileOptions {
annotationProcessorOptions {
arguments += [
"room.schemaLocation":"$projectDir/schemas".toString(),
"room.incremental":"true",
"room.expandProjection":"true"]
}
}
}
}
复制代码
配置好之后,编译运行,module 文件夹下会生成一个schemas
文件夹,其下有一个json
文件,里面包含数据库的基本信息。
{
"formatVersion": 1,
"database": {
"version": 1,
"identityHash": "xxx",
"entities": [
{
"tableName": "t_history",
"createSql": "CREATE TABLE IF NOT EXISTS `${TABLE_NAME}` (`id` INTEGER PRIMARY KEY AUTOINCREMENT, `name` TEXT, `insert_time` TEXT, `type` INTEGER NOT NULL)",
"fields": [
{
"fieldPath": "id",
"columnName": "id",
"affinity": "INTEGER",
"notNull": false
},
{
"fieldPath": "name",
"columnName": "name",
"affinity": "TEXT",
"notNull": false
},
{
"fieldPath": "insertTime",
"columnName": "insert_time",
"affinity": "TEXT",
"notNull": false
},
{
"fieldPath": "type",
"columnName": "type",
"affinity": "INTEGER",
"notNull": true
}
],
"primaryKey": {
"columnNames": [
"id"
],
"autoGenerate": true
},
"indices": [],
"foreignKeys": []
}
],
"views": [],
"setupQueries": [
"CREATE TABLE IF NOT EXISTS room_master_table (id INTEGER PRIMARY KEY,identity_hash TEXT)",
"INSERT OR REPLACE INTO room_master_table (id,identity_hash) VALUES(42, 'xxx')"
]
}
}
复制代码
ok,基本使用讲解完了,如果对你有用,点个赞呗 ^ _ ^
参考
评论