Android jetpack - Room 持久性库

一、前言

Room 持久性库属于谷歌在2018推出Android jetpack(外网)其中的软件架构组件中的一个。在谷歌开发者网站有介绍和一些例子链接Room 持久性库(外网)。本文指在介绍Room持久性库的使用。让你快速理解并上手room库。

二、简介

谷歌爸爸是这么介绍Room库的：Room 持久性库在 SQLite 的基础上提供了一个抽象层，让用户能够在充分利用 SQLite 的强大功能的同时，获享更强健的数据库访问机制。
Room是为了方便我们更简单高效的使用数据库，有助于我们书写更清晰的代码，避免很多类型错误等。

三、使用方法

Room持久性库使用也比较简单，分为三部分。

• 使用@Database的类 - 创建数据库工作
• 使用@Entity的类 - 定义表，表中有什么参数，每个参数什么类型等等，定义数据的地方
• 使用@Dao的类 - 这里定义数据库如何访问，也就是如何增删查改等

这三部分的作用定义区分还是十分明显，下面我们详细说明这三个部分具体的细节用法。在这之前你需要第一步，添加依赖项，其它用法依赖项请查看Room 依赖项(外网)

implementation "androidx.room:room-runtime:$roomVersion"
annotationProcessor "androidx.room:room-compiler:$roomVersion"

还需在defaultConfig中指定路径

//指定room.schemaLocation生成的文件路径
        javaCompileOptions {
            annotationProcessorOptions {
                arguments = ["room.schemaLocation": "$projectDir/schemas".toString()]
            }
        }

3.1、 创建数据库@Database

首先我们必须满足下面三点:

• 这个类必须extends RoomDatabase
• @Database注解参数中必须制定有@Entity来定义表参数
• 必须有一个抽象方法，且这个抽象方法返回的参数类型是用@Dao来描述的那个类
  上面是必须满足的，额外的，我们一般写成单例，重复的创建数据库等消耗也是蛮大的。

@Database(entities = Person.class,version = 1,exportSchema = false)  // 表参数
@TypeConverters({Converters.class})  // 数据转换器
public abstract class ToDoDatabase extends RoomDatabase {    // 必须继承RoomDatabase

    private volatile static ToDoDatabase INSTANCE;
    // 必须的抽象方法
    public abstract TasksDao taskDao();

    public static ToDoDatabase getInstance(Context context) {
        if (INSTANCE == null) {
            synchronized (ToDoDatabase.class) {
                if (INSTANCE == null) {
                    INSTANCE = Room.databaseBuilder(context.getApplicationContext(),
                            ToDoDatabase.class, "Tasks.db")
                            .build();
                }
            }
        }
        return INSTANCE;
    }
}

• Database注解中参数entities表示表，可以是多个表。
• 如果没指定数据库路径，必须设置exportSchema为false

public class Converters {
    @TypeConverter
    public static Date fromTimestamp(Long value) {
        return value == null ? null : new Date(value);
    }

    @TypeConverter
    public static Long dateToTimestamp(Date date) {
        return date == null ? null : date.getTime();
    }
}

• 上面数据转换提供把别的数据转换成room可以存储的数据，比如日期data，就可以转换成Long数据类型后再存储。

3.2、数据表类@Entity

定义表的类，以及表中的各种数据

@Entity(tableName = "persons",primaryKeys = {"titleId"}
    ,indices = {@Index(value = {"first_name", "last_name"},
        unique = true)})
public class Person {

    private int titleId;

    @PrimaryKey
    private int id;

    @ColumnInfo(name = "first_name")
    private String firstName;

    @ColumnInfo(name = "last_name")
    private String lastName;

    @ColumnInfo(name = "age")
    private int age;

    @Ignore
    private Bitmap face;

    @Embedded(prefix = "first")
    Address address;
    @Embedded(prefix = "second")
    Address addressTwo;
}

class Address {
    public String street;
    public String state;
    public String city;

    @ColumnInfo(name = "post_code")
    public int postCode;
}

上面有两个java文件，其中Person就是我们定义描述表的类。下面列出各个参数的用法意义

• PrimaryKey 主键，有且至少有一个，可以用@或者Entity参数指定
• ColumnInfo的name属性可指定属性的列名，不添加ColumnInfo也会根据参数名字自动生成
• Ignore 忽略，不在表中创建列
• Embedded 嵌套多个类，参数prefix作用：在列名前添加一个前缀。会自动生成firststreet,firststate等
  属性
• Entity 表示数据库中的表。可以指定tableName表名，primaryKeys主键，indices索引，Index字段组，ForeignKey外键等等用法
• 上面的各种参数，必须实现set&get方法

3.3、增删查改@Dao

3.3.1、操作类基本用法

@Dao
public interface PersonDao {
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    void insertPerson(Person person);

    @Query("DELETE FROM persons WHERE id = :id")
    void deletePerssonById(int id);

    @Query("SELECT * FROM persons")
    List getPersons();

    @Query("SELECT * FROM persons WHERE id = :id")
    Person getPersonById(int id);

    @Update
    int updataPerson(Person person);

    @Query("UPDATE persons SET firststreet = :street WHERE id = :id")
    int updatePersonAdress(int id,String street);
}

• 曾：@insert关键字，onConflict指定重复策略
• 删：@Delete关键字，或@Query的DELETE sql语句
• 查：@Query关键字，SELECT sql语句
• 改：@UPDATE关键字，或@Query的UPDATE sql语句

3.3.2、特定的返回对象

另外Room库在查询的时候还支持一些特定的返回对象。
1、返回集合
这个跟上面基本用法举例一样

 @Query("SELECT * FROM persons")
    List getPersons();

2、返回Cursor

@Dao
public interface MyDao {
    @Query("SELECT * FROM user WHERE age > :minAge LIMIT 5")
    public Cursor loadRawUsersOlderThan(int minAge);
}

3、返回Rxjava中的Publisher和Flowable对象

@Dao
public interface MyDao {
    @Query("SELECT * from user where id = :id LIMIT 1")
    public Flowable loadUserById(int id);
}

4、返回LiveData对象

@Dao
public interface MyDao {
    @Query("SELECT first_name, last_name FROM user WHERE region IN (:regions)")
    public LiveData> loadUsersFromRegionsSync(List regions);
}

3.4、数据库升级

3.4.1、方式一：清空以前所有数据创建新的

@Database(entities = {User.class}, version = 2)
public abstract class UsersDatabase extends RoomDatabase

database = Room.databaseBuilder(context.getApplicationContext(),
                        UsersDatabase.class, "Sample.db")
                 //添加下面这一行
                .fallbackToDestructiveMigration()
                .build();

添加了新的版本，干掉了以前的。

3.4.2、方式二：添加新的，保留之前的

@Database(entities = {User.class}, version = 3)
public abstract class UsersDatabase extends RoomDatabase

static final Migration MIGRATION_1_2 = new Migration(1, 2) {
    @Override
    public void migrate(SupportSQLiteDatabase database) {
      //此处对于数据库中的所有更新或者添加都要写在这里
        database.execSQL("ALTER TABLE users "
                + " ADD COLUMN last_update INTEGER");
    }
};

database = Room.databaseBuilder(context.getApplicationContext(),
        UsersDatabase.class, "Sample.db")
         //增加下面这一行
        .addMigrations(MIGRATION_1_2)
        .build();

方式一和方式二的实际区分就在build的时候调用方法不同。注意方式二的时候添加新的字段或者改变都要用sql语句描述。

四、写在最后

Room持久性库给我们简化了很多操作，真的方便了很多。而且在数据设计之初就能帮助我们避免不少类型转换的错误。是我们不错的一个选择。在本地数据管理上，谷歌也推荐我们采用此方式。