Room是一个对象关系映射库，以最少的代码提供本地数据持久化功能。它在编译时验证每个查询，所以损坏的SQL查询只会导致编译时错误而不是运行时崩溃。Room抽象了部分SQL查询与表的相关操作的底层细节。它还可以让你通过一个LiveData对象监听到数据库数据的变化。另外，它还明确定义了线程约束，解决了诸如从主线程获取存储这样的常见的问题。
Room在SQLite上提供了一个抽象层，以便在利用SQLite的全部功能的同时使流畅的数据库访问。
Room主要有 三个组成部分：
Database ：在运行时，您可以通过调用Room.databaseBuilder（）或Room.inMemoryDatabaseBuilder（）获取一个实例
Entity：表示一个保存数据库行的类。对于每个实体，创建一个数据库表来保存项目。您必须通过Database类中的entities数组引用实体类。实体的每个字段都保存在数据库中，除非您使用@Ignore注释它
实体可以有空构造函数（如果DAO类可以访问每个持久化字段），或者一个构造函数的参数包含类型和名称与实体中的字段匹配的构造函数。
- DAO：表示作为数据访问对象（DAO）的类或接口。 DAO是Room的主要组件，负责定义访问数据库的方法。用@Database注释的类必须包含一个具有0个参数的抽象方法，并返回使用@Dao注释的类。在编译时生成代码时，Room创建一个这个类的实现。
通过使用DAO类而不是查询构建器或直接查询访问数据库，您可以分离数据库体系结构的不同组件。此外，DAO允许您在测试应用程序时轻松地模拟数据库访问。
这些组件及其与应用程序其余部分的关系如图1所示：
以下代码片段包含具有1个实体和1个DAO的示例数据库配置：
@Entity
public class User {
@PrimaryKey
private int uid;
@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.
}
@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);
}
@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();
实例化AppDatabase对象时，应遵循单例设计模式，因为每个数据库实例都相当昂贵，而且很少需要访问多个实例
Entity
当类被@Entity注释并且在@Database注释的entities属性中引用时，Room会在数据库中为该实体创建一个数据库表。
默认情况下，Room为实体中定义的每个字段创建一个列。如果一个实体具有不想持久化的字段，可以使用@Ignore对它们进行注释，如下面的代码片段所示：
@Entity
class User {
@PrimaryKey
public int id;
public String firstName;
public String lastName;
@Ignore
Bitmap picture;
}
可以使用@Entity注释的primaryKeys属性，如以下代码片段所示：
@Entity(primaryKeys = {"firstName", "lastName"})
class User {
public String firstName;
public String lastName;
@Ignore
Bitmap picture;
}
默认情况下，Room使用类名作为数据库表名。如果希望表具有不同的名称，请设置@Entity注释的tableName属性，如以下代码片段所示
@Entity(tableName = "users")
class User {
...
}
与tablename属性类似，Room使用字段名作为数据库中的列名。如果您希望列具有不同的名称，请将@ColumnInfo注释添加到字段中，如以下代码片段所示：
@Entity(tableName = "users")
class User {
@PrimaryKey
public int id;
@ColumnInfo(name = "first_name")
public String firstName;
@ColumnInfo(name = "last_name")
public String lastName;
@Ignore
Bitmap picture;
}
索引和唯一性
根据访问数据的方式，您可能希望对数据库中的某些字段进行索引，以加快查询速度。要向实体添加索引，请在@Entity注释中包含indices属性，列出要包括在索引或组合索引中的列的名称。以下代码片段演示了此注释过程：
@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注释的唯一属性设置为true来强制执行此唯一性属性。
@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;
}
关系
因为SQLite是一个关系数据库，您可以指定对象之间的关系。即使大多数ORM库允许实体对象相互引用，Room严禁这一点。
即使您不能使用直接关系，Room仍允许您在实体之间定义Foreign Key约束。
例如，如果有另一个名为Book的实体，您可以使用@ForeignKey注释来定义与User实体的关系，如以下代码片段所示：
@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;
}
ForeignKey非常强大，因为它们允许您指定引用实体更新时发生的情况。例如，如果通过在@ForeignKey注释中包含onDelete = CASCADE删除了相应的User实例，则可以告诉SQLite删除用户的所有book。
嵌套对象
有时候，您希望在数据库逻辑中表达一个实体或普通的Java对象（POJO），即使对象包含多个字段。在这些情况下，您可以使用@Embedded注释来表示要在表中分解为子字段的对象。然后，您可以像其他单独的列一样查询嵌入的字段。
例如，我们的User类可以包含一个Address类型的字段，它表示一个名为street，city，state和postCode的字段的组合。要将表格中单独存储组合列
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;
}
User对象的表包含以下名称的列：id，firstName，street，state，city和post_code。
Data Access Objects (DAOs)
DAO以干净的方式抽象地访问数据库。
如果@Insert方法只接收到一个参数，它可以返回一个long，这是插入项的新rowId。如果参数是数组或集合，它应该返回long []或List <Long>。
@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);
@Update
public void updateUsers(User... users);
@Delete
public void deleteUsers(User... users);
}
查询语句 @Query
@Query是DAO类中使用的主要注释。它允许您对数据库执行读/写操作。每个@Query方法都在编译时被验证，因此，如果查询有问题，则会发生编译错误，而不是运行时故障。
Room还验证查询的返回值，以便如果返回对象中的字段名称与查询响应中相应的列名称不匹配，则房间将以以下两种方式之一提醒您:
- 如果只有一些字段名称匹配，则会发出警告
- 如果没有字段名称匹配，则会给出错误
将参数传递到查询中
@Dao
public interface MyDao {
@Query("SELECT * FROM user WHERE age BETWEEN :minAge AND :maxAge")
public User[] loadAllUsersBetweenAges(int minAge, int maxAge);
@Query("SELECT * FROM user WHERE first_name LIKE :search "
+ "OR last_name LIKE :search")
public List<User> findUserWithName(String search);
@Query("SELECT first_name, last_name FROM user WHERE region IN (:regions)")
public List<NameTuple> loadUsersFromRegions(List<String> regions);
}
观察查询结果
执行查询时，您经常希望应用程序的UI在数据更改时自动更新。要实现这一点，请在查询方法描述中使用类型为LiveData的返回值，当数据库更新时，Room会生成所有必需的代码来更新LiveData。
@Dao
public interface MyDao {
@Query("SELECT first_name, last_name FROM user WHERE region IN (:regions)")
public LiveData<List<User>> loadUsersFromRegionsSync(List<String> regions);
}
Room使用查询中访问的表的列表来决定是否更新LiveData对象
RXJava
Room还可以从您定义的查询中返回RxJava2 Publisher和Flowable对象
@Dao
public interface MyDao {
@Query("SELECT * from user where id = :id LIMIT 1")
public Flowable<User> loadUserById(int id);
}
直接访问Cursor
如果您的应用程序的逻辑需要直接访问返回行，则可以从查询中返回一个Cursor对象，如以下代码片段所示：
@Dao
public interface MyDao {
@Query("SELECT * FROM user WHERE age > :minAge LIMIT 5")
public Cursor loadRawUsersOlderThan(int minAge);
}
非常不鼓励使用Cursor API，因为它不能保证行是存在还是行包含的值。仅当您已经具有期望Cursor 的代码并且不能轻易重构时，才能使用此功能
多表查询
您的一些查询可能需要访问多个表以计算结果。Room允许你编写任何查询，所以你也可以连接表。此外如果响应是可观察的数据类型，例如Flowable或LiveData，则Room会监视查询中引用的无效的所有表。
类型转换
有时候您希望使用自定义数据类型将数据存储在单个列中。要为自定义类型添加这种支持，您可以提供一个TypeConverter，它将一个自定义类转换为Room可以保留的已知类型。
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已经知道如何持久化Long对象，因此可以使用此转换器来持久保存Date类型的值。
接下来，您将@TypeConverters注释添加到AppDatabase类，以便Room可以使用您为该AppDatabase中的每个实体和DAO定义的转换器：
@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);
}
数据迁移
当您添加和更改应用程序中的功能时，您需要修改实体类以反映这些更改。当用户更新到最新版本的应用程序时，您不希望它们丢失所有现有数据，特别是如果您无法从远程服务器恢复数据。
Room允许您以这种方式编写迁移类来保留用户数据。每个Migration类都指定和版本。在运行时，Room运行每个Migration类的migrate（）方法，如果您没有提供必要的迁移，则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");
}
};
