Room Persistence Library

Android Architecture Components 基本介绍和使用方式见，Android架构组件

Room提供了一个抽象层，允许流畅的访问SQLite数据库，全面强大的直接SQLite。
Android框架提供了支持原始SQL内容的内置支持。虽然这些API是强大的，但是水平相当低，需要大量的时间和精力使用：
原始SQL查询没有编译时验证。由于数据图表的更改，需要手动更新受影响的sql查询。这个过程是费时和容易出错的。
你需要使用大量的样板代码的SQL查询和java数据对象之间的转换。

Room为了解决这些问题在SQLite提供一个抽象层。
Room有3个主要组成部分：

• Database: 可以使用此组件创建数据库 holder，注释定义实体列表，和类的内容定义数据访问对象（DAO）数据库中的表。它也是基本连接的主要访问点。
• Entity: 实体类对象模型，一般一对一对应表结构。实体的每个字段在数据库中都是保存的，除非你用@Ignore 注解。
• DAO: 数据库操作接口，一般一对一对应表的相关操作
  这些组件，以及它们与应用程序其余部分的关系，如图所示：

Entity

User.java

//@Entity用来注解一个实体类，对应数据库一张表
@Entity
public class User {
    //@PrimaryKey 主键
    @PrimaryKey
    private int uid;
    //@ColumnInfo 对应的数据库的字段名成
    @ColumnInfo(name = "first_name")
    private String firstName;

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

    // Getters and setters are ignored for brevity,
    // but they're required for Room to work.
}

默认情况下，Room为实体中定义的每个成员变量在数据中创建对应的字段，我们可能不想保存到数据库的字段，这时候就要用道@Ignore注解

@Entity
class User {
    @PrimaryKey
    public int id;

    public String firstName;
    public String lastName;

    @Ignore
    Bitmap picture;
}

注意：为了保存每一个字段，这个字段需要有可以访问的gettter/setter方法或者是public的属性

Entity的参数 primaryKeys

每个实体必须至少定义1个字段作为主键,即使只有一个成员变量，除了使用@PrimaryKey 将字段标记为主键的方式之外，还可以通过在@Entity注解中指定参数的形式

@Entity(primaryKeys = {"firstName", "lastName"})
class User {
    public String firstName;
    public String lastName;

    @Ignore
    Bitmap picture;
}

Entity的参数 tableName

默认情况下，Room使用类名作为数据库表名。如果你想表都有一个不同的名称，就可以在@Entity中使用tableName参数指定

@Entity(tableName = "users")
class User {
    ...
}

和tableName作用类似； @ColumnInfo注解是改变成员变量对应的数据库的字段名成

Entity的参数 indices

indices的参数值是@Index的数组，在某些情况写为了加快查询速度我们可以需要加入索引

@Entity(indices = {@Index("name"), @Index("last_name", "address")})
class User {
    @PrimaryKey
    public int id;

    public String firstName;
    public String address;

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

    @Ignore
    Bitmap picture;
}

有时，数据库中某些字段或字段组必须是唯一的。通过将@Index的unique 设置为true，可以强制执行此唯一性属性。下面的代码示例防止表有两行包含FirstName和LastName列值相同的一组：

@Entity(indices = {@Index(value = {"first_name", "last_name"},
        unique = true)})
class User {
    @PrimaryKey
    public int id;

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

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

    @Ignore
    Bitmap picture;
}

Entity的参数 foreignKeys

因为SQLite是一个关系型数据库，你可以指定对象之间的关系。尽管大多数ORM库允许实体对象相互引用，但Room明确禁止。实体之间没有对象引用。

不能使用直接关系，所以就要用到foreignKeys（外键）。

@Entity(foreignKeys = @ForeignKey(entity = User.class,
                                  parentColumns = "id",
                                  childColumns = "user_id"))
class Book {
    @PrimaryKey
    public int bookId;

    public String title;

    @ColumnInfo(name = "user_id")
    public int userId;
}

外键是非常强大的，因为它允许指定引用实体更新时发生的操作。例如，级联删除，你可以告诉SQLite删除所有书籍的用户如果用户对应的实例是由包括OnDelete =CASCADE在@ForeignKey注释。ON_CONFLICT ： @Insert(onConflict=REPLACE) REMOVE 或者 REPLACE

有时候可能还需要对象嵌套这时候可以用@Embedded注解

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

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

@Entity
class User {
    @PrimaryKey
    public int id;

    public String firstName;

    @Embedded
    public Address address;
}

Dao

UserDao.java

@Dao
public interface UserDao {
    @Query("SELECT * FROM user")
    List<User> getAll();

    @Query("SELECT * FROM user WHERE uid IN (:userIds)")
    List<User> loadAllByIds(int[] userIds);

    @Query("SELECT * FROM user WHERE first_name LIKE :first AND "
           + "last_name LIKE :last LIMIT 1")
    User findByName(String first, String last);

    @Insert
    void insertAll(User... users);

    @Delete
    void delete(User user);
}

数据访问对象Data Access Objects (DAOs)是一种抽象访问数据库的干净的方式。

DAO的Insert 操作

当创建DAO方法并用@Insert注释它时，生成一个实现时会在一个事务中完成插入所有参数到数据库。

@Dao
public interface MyDao {
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    public void insertUsers(User... users);

    @Insert
    public void insertBothUsers(User user1, User user2);

    @Insert
    public void insertUsersAndFriends(User user, List<User> friends);
}

DAO的Update、Delete操作

与上面的插入类似

@TypeConverte

类型转换，例如：

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();
    }
}

前面的例子定义了2个函数，一个将Date对象转换为一个Long对象，另一个Long到Date的逆转换。因为Room已经知道如何保存Long对象，所以可以使用这个转换器来保存类型Date的值。@TypeConverters的使用

@Database(entities = {User.java}, version = 1)
@TypeConverters({Converter.class})
public abstract class AppDatabase extends RoomDatabase {
    public abstract UserDao userDao();
}
@Entity
public class User {
    ...
    private Date birthday;
}
@Dao
public interface UserDao {
    ...
    @Query("SELECT * FROM user WHERE birthday BETWEEN :from AND :to")
    List<User> findUsersBornBetweenDates(Date from, Date to);
}

Database

@Database(entities = {User.class}, version = 1)
public abstract class AppDatabase extends RoomDatabase {
    public abstract UserDao userDao();
}

在创建上述文件之后，您将使用以下代码获取创建的数据库实例：

AppDatabase db = Room.databaseBuilder(getApplicationContext(),
        AppDatabase.class, "database-name").build();

Database migration 数据库迁移（升级）

版本迭代中，我们不可避免的会遇到数据库升级问题Room也为我们提供了数据库升级的处理接口；

Room.databaseBuilder(getApplicationContext(), MyDb.class, "database-name")
        .addMigrations(MIGRATION_1_2, MIGRATION_2_3).build();

static final Migration MIGRATION_1_2 = new Migration(1, 2) {
    @Override
    public void migrate(SupportSQLiteDatabase database) {
        database.execSQL("CREATE TABLE `Fruit` (`id` INTEGER, "
                + "`name` TEXT, PRIMARY KEY(`id`))");
    }
};

static final Migration MIGRATION_2_3 = new Migration(2, 3) {
    @Override
    public void migrate(SupportSQLiteDatabase database) {
        database.execSQL("ALTER TABLE Book "
                + " ADD COLUMN pub_year INTEGER");
    }
};

迁移过程结束后，Room将验证架构以确保迁移正确发生。如果Room发现问题，则抛出包含不匹配信息的异常。
警告：如果不提供必要的迁移，Room会重新构建数据库，这意味着将丢失数据库中的所有数据。

输出模式

可以在gradle中设置开启输出模式，便于我们调试，查看数据库表情况，以及做数据库迁移。

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