Android Room 使用详解

介绍

Room是Google提供的一个ORM库。Room提供了三个主要的组件：

• @Database：@Database用来注解类，并且注解的类必须是继承自RoomDatabase的抽象类。该类主要作用是创建数据库和创建Daos（data access objects，数据访问对象）。

• @Entity：@Entity用来注解实体类，@Database通过entities属性引用被@Entity注解的类，并利用该类的所有字段作为表的列名来创建表。

• @Dao：@Dao用来注解一个接口或者抽象方法，该类的作用是提供访问数据库的方法。在使用@Database注解的类中必须定一个不带参数的方法，这个方法返回使用@Dao注解的类。

使用Room

• 添加google Maven 仓库

allprojects {    repositories {        jcenter()        maven { url 'https://maven.google.com' }    }}

• 添加Room依赖

dependencies {    def room_version = "2.5.0"    implementation "Androidx.room:room-runtime:$room_version"    annotationProcessor "androidx.room:room-compiler:$room_version"    // To use Kotlin annotation processing tool (kapt)    kapt "androidx.room:room-compiler:$room_version"    // To use Kotlin Symbol Processing (KSP)    ksp "androidx.room:room-compiler:$room_version"    // optional - RxJava2 support for Room    implementation "androidx.room:room-rxjava2:$room_version"    // optional - RxJava3 support for Room    implementation "androidx.room:room-rxjava3:$room_version"    // optional - Guava support for Room, including Optional and ListenableFuture    implementation "androidx.room:room-guava:$room_version"    // optional - Test helpers    testImplementation "androidx.room:room-testing:$room_version"    // optional - Paging 3 Integration    implementation "androidx.room:room-paging:$room_version"}

例子

User.java

@Entitypublic 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.}

UserDao.java

@Daopublic interface UserDao {    @Query("SELECT * FROM user")    List getAll();    @Query("SELECT * FROM user WHERE uid IN (:userIds)")    List 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);}

AppDatabase.java

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

获取AppDatabase实例：

AppDatabase db = Room.databaseBuilder(getApplicationContext(),        AppDatabase.class, "user.db").build();

每次创建AppDatabase实例都会产生比较大的开销，所以应该将AppDatabase设计成单例的。

@Database(entities = {User.class}, version = 1, exportSchema = false)public abstract class AppDatabase extends RoomDatabase {  private static AppDatabase INSTANCE;  private static final Object sLock = new Object();  public abstract UserDao userDao();  public static AppDatabase getInstance(Context context) {    synchronized (sLock) {      if (INSTANCE == null) {        INSTANCE =            Room.databaseBuilder(context.getApplicationContext(), AppDatabase.class, "roomName.db").allowMainThreadQueries().build();      }      return INSTANCE;    }  }}

Entity

Room会利用@Entity注解的类的所有字段来创建表的列，如果某些字段不希望存储的话，使用@Ignore注解该字段即可。

@Entityclass User {    @PrimaryKey    public int id;    public String firstName;    public String lastName;    @Ignore    Bitmap picture;}

默认情况下，Room使用类名作为表名，使用字段名作为列名。我们可以通过@Entity的tableName属性定义自己的表名，通过@ColumnInfo的name属性定义自己的列名。

sqlite中的表名不区分大小写。

@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;}

主键

每个实体必须定义至少1个字段作为主键。即使只有1个字段，仍然需要用@PrimaryKey注解字段。此外，如果您想Room自动分配IDs给实体，则可以设置@PrimaryKey的autoGenerate属性。如果实体具有复合主键，则可以使用@Entity注解的primaryKeys属性，如下面的代码片段所示：

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

索引和唯一性

需要索引数据库中的某些列以加快查询速度。若要向实体添加索引，在@Entity注释中添加indices属性 ，下面的代码片段演示了这个注解过程：

@Entity(indices = {@Index("name"),        @Index(value = {"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，来确保唯一性。在下面的例子中，防止first_name和last_name这两列同时具有相同的数据。

@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仍然两个实体之间定义外键。

例如，有另外一个实体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的onDelete属性值为CASCADE，如果删除user，所有具有相同userId的book会被全部删除。

嵌套对象

假设我们的User实体中新加了下面这些字段：

public class User {  @PrimaryKey(autoGenerate = true)  public int id;  public String firstName;  public String lastName;  //  @Ignore Bitmap picture;  public String street;  public String state;  public String city;  @ColumnInfo(name = "post_code")  public int postCode;}

创建的表

这样看起来一点也不面向对象，我们完全可以将新加的字段封装成一个Address对象。

class Address {    public String street;    public String state;    public String city;    @ColumnInfo(name = "post_code")    public int postCode;}

Room提供了一个注解@Embedded，允许在一个实体中嵌入另外一个实体，创建的表使用的是当前实体和嵌入实体的所有字段，所以我们可以修改上面的User实体

@Entityclass User {  @PrimaryKey(autoGenerate = true)   public int id;  public String firstName;  public String lastName;  //  @Ignore   Bitmap picture;  @Embedded  public Address address;}

当一个类中嵌套多个类，并且这些类具有相同的字段，则需要调用@Embedded的属性prefix 添加一个前缀，生成的列名为前缀+列名

public class User {  @PrimaryKey(autoGenerate = true)   public int id;  public String firstName;  public String lastName;  @Embedded(prefix = "first")  Address address;  @Embedded(prefix = "second")  AddressTwo addressTwo;}

该例中将会创建firstStreet，firstState...secondStreet，secondState...等列。

数据访问对象（DAOs）

DAO既可以是接口，也可以是抽象类。如果是抽象类，它可以有一个构造函数，它把RoomDatabase作为唯一的参数。Room在编译时创建每个DAO实现。

Insert

当我们创建一个Dao方法，并使用@Insert注解，Room将把所有的参数在一次事物中插入到数据库中。

@Daopublic 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 friends);}

如果@Insert方法只接收1个参数，则可以返回一个Long型的值，这是插入项的新rowId。如果参数是数组或集合，则应该返回long[] 或者 List类型的值。

有时插入数据和更新数据会产生冲突,所以就有了冲突之后要怎么解决,SQLite对于事务冲突定义了5个方案

OnConflictStrategy

• REPLACE:见名知意,替换,违反的记录被删除，以新记录代替之

• ignore: 违反的记录保持原貌，其它记录继续执行

• fail: 终止命令，违反之前执行的操作得到保存

• abort 终止命令，恢复违反之前执行的修改

• rollback 终止命令和事务，回滚整个事务

Update

使用@Update注解方法，可以使用参数实体的值更新主键值和参数实体的主键相同的行。

@Daopublic interface MyDao {    @Update    public void updateUsers(User... users);}

@Update注解的方法还可以返回int，表示受影响的行数。

Delete

使用@Delete注解方法，可以删除主键值和参数实体的主键相同的行。

@Daopublic interface MyDao {    @Delete    public void deleteUsers(User... users);}

@Delete注解的方法还可以返回int，表示删除的行数。

Query

@Query的值为SQL语句，可以被SQLite执行。@Query支持查询语句，删除语句和更新语句，不支持插入语句。

@Query是DAO类中使用的主要注解。它允许您在数据库上执行读/写操作。每个@Query方法在编译时被验证，因此，如果存在查询问题，则会发生编译错误而不是运行时故障。

Room还验证查询的返回值，这样如果返回对象中字段的名称与查询响应中的相应列名不匹配，则Room将以以下两种方式之一提醒您：

• 如果只有一些字段名匹配，则发出警告。

• 如果没有字段名匹配，则会出错。

@Daopublic interface MyDao {    @Query("SELECT * FROM user")    public User[] loadAllUsers();}

传入参数

Room会在编译时进行检查，当代码中包含语法错误，或者表不存在，Room将在编译时出现错误信息。

如果我们想获取指定id的用户，该怎么办。@Query的value中支持添加绑定参数，该参数必须找到与之匹配的方法参数，并取得该方法参数的值。

@Daopublic interface MyDao {//传入单个参数    @Query("SELECT * FROM user WHERE age > :minAge")    public User[] loadAllUsersOlderThan(int minAge);}

在这个例子中绑定参数:minAge与方法参数minAge相匹配。

而且允许传入多个参数，或者多次引用相同的参数

@Daopublic 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 findUserWithName(String search);}

此外，Room还允许传入一个参数集合

@Daopublic interface MyDao {    @Query("SELECT first_name, last_name FROM user WHERE region IN (:regions)")    public List loadUsersFromRegions(List regions);}

返回列的子集

多数情况下，你只需要获取实体的少数几个字段。例如，你的ui可能只展示用户的名和姓，而不是每个用户的详细信息。通过只获取需要的列，可以节省资源，并且查询速度更快。

只要可以将查询的结果映射到返回的对象上，Room允许返回任何java对象。例如，可以创建如下java对象来获取用户的名和姓。

public class NameTuple {    @ColumnInfo(name="first_name")    public String firstName;    @ColumnInfo(name="last_name")    public String lastName;}

在查询方法中使用该对象

@Daopublic interface MyDao {    @Query("SELECT first_name, last_name FROM user")    public List loadFullName();}

如果返回的列NameTuple不存在对应的字段，编译时会出现警告。

Observable查询

当执行查询时，您经常希望应用程序的UI在数据更改时自动更新。要实现这一点，请在查询方法描述中使用类型LiveData的返回值。当数据库被更新时，Room生成所有必要的代码来更新LiveData。

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

RxJava的响应式查询

Room还可以从您定义的查询中返回RxJava2 Publisher和Flowable对象。若要使用此功能，请将androidx.room:room-rxjava2库添加到gradle的依赖关系中。

@Daopublic interface MyDao {    @Query("SELECT * from user where id = :id LIMIT 1")    public Flowable loadUserById(int id);    // Emits the number of users added to the database.    @Insert    public Maybe insertLargeNumberOfUsers(List users);    // Makes sure that the operation finishes successfully.    @Insert    public Completable insertLargeNumberOfUsers(User... users);        @Delete    public Single deleteUsers(List users);}

直接返回Cursor

Room还可以直接返回Cursor对象。

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

查询多个表

@Daopublic interface MyDao {    @Query("SELECT * FROM book "           + "INNER JOIN loan ON loan.book_id = book.id "           + "INNER JOIN user ON user.id = loan.user_id "           + "WHERE user.name LIKE :userName")   public List findBooksBorrowedByNameSync(String userName);}

类型转换器

Room支持字符串和基本数据类型以及他们的包装类，但是如果不是基本数据类型，该如何存储呢？比如我们的User对象有个Date类型的字段birthday，我们该如何存储。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可以调用dateToTimestamp方法将Date转化为Long类型进行存储，也可以在查询的时候调用fromTimestamp将获取的Long转换为Date对象。

为了让Room调用该转换器，使用@TypeConverters注解将转换器添加到AppDatabase上。

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

数据库升级

在app发布以后，我们可能会新增表或者修改原来表的结构，这就需要升级数据库。Room提供了 Migration 类用于迁移数据库，每一个 Migration 需要在构造函数里指定开始版本和结束版本。在运行时，Room会按照提供版本的顺序顺序执行每个Migration的migrate()方法，将数据库升级到最新的版本。

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 ctime TEXT");        //database.execSQL("ALTER TABLE Book "        //       + " ADD COLUMN pub_year INTEGER NOT NULL DEFAULT 0");        //当添加int 类型数据时，需要添加默认值    }};

注：当添加int (INTEGER) 类型数据时，需要添加默认值

参考于：

https://www.jianshu.com/p/7354d5048597

https://www.jianshu.com/p/0ed8b17a199e

https://developer.android.google.cn/training/data-storage/room?hl=zh-cn

来源地址：https://blog.csdn.net/Snow_Ice_Yang/article/details/128929138