Use of jetpack's room in combination with flow

This article mainly refers to official documents , Then take saving the search history as an example to operate a wave .

preparation

Room

  stay  

SQLite

  An abstraction layer is provided on , In order to make full use of  SQLite  At the same time , Be able to access the database smoothly .

rely on

For use in applications

 Room

, Please add the following dependencies to the application  

build.gradle 

file .

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"
}


Main components

• database
  ： Include database holders , And as the main access point of the underlying connection of the application of the retained persistent relational data . Use  
  @Database
  Annotated classes should meet the following conditions ：

• It 's an extension  
  RoomDatabase
    The abstract class of .

• Add a list of entities associated with the database to the comment .

• Include with  0  And return to use
  @Dao
  Abstract methods of annotated classes . At run time , You can call  
  Room.databaseBuilder()
    or  
  Room.inMemoryDatabaseBuilder() 
  obtain  
  Database 
  Example .

• Entity
  ： Represents a table in a database .

• DAO
  ： Contains methods for accessing the database .

Application and use  Room  Database to get the data access objects associated with the database  (DAO). then , The app uses each  DAO  Get entities from the database , Then save all changes to these entities back to the database .  Last , The application uses entities to get and set the values corresponding to the table columns in the database .

The relationship is as shown in the figure ：

ok, After understanding the basic concepts , Let's see what happened .

Entity

@Entity(tableName = "t_history")
data class History(

 /**
 * @PrimaryKey Primary key ,autoGenerate = true  Self increasing
 * @ColumnInfo  Column  ,typeAffinity  Field type
 * @Ignore  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 Object corresponds to a table , Use
  @Entity
  annotation , And declare your table name

• @PrimaryKey
    Primary key ,
  autoGenerate = true
    Self increasing

• @ColumnInfo
    Column , And declare the listing  ,
  typeAffinity
    Field type

• @Ignore
    Declare ignored objects

A very simple table , Mainly

name

and

insertTime

Field .

DAO

@Dao
interface HistoryDao {

 // By type   Query all search history
 @Query("SELECT * FROM t_history WHERE type=:type")
 fun getAll(type: Int = 1): Flow<List<History>>

 @ExperimentalCoroutinesApi
 fun getAllDistinctUntilChanged() = getAll().distinctUntilChanged()

 // Add a search history
 @Insert
 fun insert(history: History)

 // Delete a search history
 @Delete
 fun delete(history: History)

 // Update a search history
 @Update
 fun update(history: History)

 // according to id  Delete a search history
 @Query(&quot;DELETE FROM t_history WHERE id = :id&quot;)
 fun deleteByID(id: Int)

 // Delete all search history
 @Query(&quot;DELETE FROM t_history&quot;)
 fun deleteAll()
}


• @Insert： increase

• @Delete： Delete

• @Update： Change

• @Query： check

Here's a point to note , Namely

Query all search history

The returned set I use

Flow

Modify the .

As long as any data in the database is updated , No matter which row of data is changed , Then re execute  

query 

Operate and redistribute

 Flow

.

In the same way , If an unrelated data is updated ,

Flow 

Will also be distributed , Will receive the same data as before .

This is because  SQLite  The content update notification function of the database is based on table  (Table)  Data is in , Instead of doing  (Row)  Data is in , Therefore, as long as the data in the table is updated , It triggers a content update notification .Room  I don't know which data is updated in the table , So it will trigger again  DAO  As defined in  query  operation . You can use  Flow  The operator of , such as  distinctUntilChanged  To ensure that you are notified only when the data you care about is updated .

 // By type   Query all search history
 @Query("SELECT * FROM t_history WHERE type=:type")
 fun getAll(type: Int = 1): Flow<List<History>>

 @ExperimentalCoroutinesApi
 fun getAllDistinctUntilChanged() = getAll().distinctUntilChanged()


database

@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

 // Be careful ： If your application runs in a single process , In instantiation  AppDatabase  Object should follow the singleton design pattern .
 // Every  RoomDatabase  The cost of an instance is quite high , You hardly need to access multiple instances in a single process
 fun getInstance(context: Context): HistoryDatabase {
 if (!this::mPersonDatabase.isInitialized) {
 // Create an instance of the database
 mPersonDatabase = Room.databaseBuilder(
 context.applicationContext,
 HistoryDatabase::class.java,
 DATABASE_NAME
 ).build()
 }
 return mPersonDatabase
 }
 }

}


• Use
  @Database
  Note statement

• entities
    Array , Corresponds to all tables in this database

• version
    Database version number

Be careful ：

If your application runs in a single process , In instantiation  AppDatabase  Object should follow

Singleton design pattern

.  Every  RoomDatabase The cost of an instance is quite high , You hardly need to access multiple instances in a single process .

Use

Get the database where you need it

mHistoryDao = HistoryDatabase.getInstance(this).historyDao()


Get search history

 private fun getSearchHistory() {
 MainScope().launch(Dispatchers.IO) {
 mHistoryDao.getAll().collect {
 withContext(Dispatchers.Main){
 // to update ui
 }
 }
 }
 }


collect

  yes

Flow

How to get the data , It's not the only way , Sure

To view the document

.

Why put it in

coroutines

Inside? , Because the operation of the database is time-consuming , The coroutine can easily specify the thread , This does not block

UI

Threads .

see Flow The source code also found ,Flow It's under the collaborative process package

package kotlinx.coroutines.flow


With collect For example , Also by

suspend

  Embellished , Since we support it

Hang up

, That cooperation

coroutines

Beauty is not true .

 @InternalCoroutinesApi
 public suspend fun collect(collector: FlowCollector<T>)


Save search records

 private fun saveSearchHistory(text: String) {
 MainScope().launch(Dispatchers.IO) {
 mHistoryDao.insert(History(null, text, DateUtils.longToString(System.currentTimeMillis())))
 }
 }


Clear local history

 private fun cleanHistory() {
 MainScope().launch(Dispatchers.IO) {
 mHistoryDao.deleteAll()
 }
 }


author ：

https://blog.csdn.net/yechaoa

Database upgrade

Database upgrade is an important operation , After all, it may cause data loss , It is also a very serious problem .

Room adopt

Migration

Class to perform the upgrade operation , We just tell

Migration

Just change the class , such as

newly added

Field or table .

Definition Migration class

 /**
 *  Database version  1->2 t_history The form added updateTime Column
 */
 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")
 }
 }
 /**
 *  Database version  2->3  newly added label surface
 */
 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

Receive two parameters ：

• startVersion  The old version

• endVersion  The new version

Notify database update

 mPersonDatabase = Room.databaseBuilder(
 context.applicationContext,
 HistoryDatabase::class.java,
 DATABASE_NAME
 ).addMigrations(MIGRATION_1_2, MIGRATION_2_3)
 .build()


Complete code

@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) {
 // Create an instance of the database
 mPersonDatabase = Room.databaseBuilder(
 context.applicationContext,
 HistoryDatabase::class.java,
 DATABASE_NAME
 ).addMigrations(MIGRATION_1_2, MIGRATION_2_3)
 .build()
 }
 return mPersonDatabase
 }

 /**
 *  Database version  1->2 t_history The form added updateTime Column
 */
 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")
 }
 }

 /**
 *  Database version  2->3  newly added label surface
 */
 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)")
 }
 }
 }

}


Be careful ：

@Database

Change of version number in annotation , If it is a new table ,

entities 

Parameters should also be added .

It is recommended to upgrade the operation sequence

Change the version number  ->  add to Migration ->  Add to databaseBuilder

Configure compiler options

Room  Processor options with the following annotations ：

• room.schemaLocation
  ： Configure and enable the export of database schema to a given directory  JSON  File functionality . For details , see also  Room  transfer .

• room.incremental
  ： Enable  Gradle  Incremental annotation processor .

• room.expandProjection
  ： To configure  Room  To rewrite the query , Make its top star projection contain only  DAO  Method returns the column defined in the type .

android {
 ...
 defaultConfig {
 ...
 javaCompileOptions {
 annotationProcessorOptions {
 arguments += [
 "room.schemaLocation":"$projectDir/schemas".toString(),
 "room.incremental":"true",
 "room.expandProjection":"true"]
 }
 }
 }
}


After configuration , Compile operation ,module A... Will be generated under the folder

schemas

Folder , Below it is a

json

file , It contains the basic information of the database .

{
 "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, Finished explaining the basic use , If it works for you , A great bai  ^ _ ^

Reference resources

• Room Official documents

• Room Update log

• Flow Official documents

• actual combat  |  stay  Room  Use in  Flow

• coroutines  Flow  Best practices  |  be based on  Android  Developer summit applications