当前位置:   article > 正文

Android Room 使用详解

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 仓库

  1. allprojects {
  2. repositories {
  3. jcenter()
  4. maven { url 'https://maven.google.com' }
  5. }
  6. }
  • 添加Room依赖

  1. dependencies {
  2. def room_version = "2.5.0"
  3. implementation "androidx.room:room-runtime:$room_version"
  4. annotationProcessor "androidx.room:room-compiler:$room_version"
  5. // To use Kotlin annotation processing tool (kapt)
  6. kapt "androidx.room:room-compiler:$room_version"
  7. // To use Kotlin Symbol Processing (KSP)
  8. ksp "androidx.room:room-compiler:$room_version"
  9. // optional - RxJava2 support for Room
  10. implementation "androidx.room:room-rxjava2:$room_version"
  11. // optional - RxJava3 support for Room
  12. implementation "androidx.room:room-rxjava3:$room_version"
  13. // optional - Guava support for Room, including Optional and ListenableFuture
  14. implementation "androidx.room:room-guava:$room_version"
  15. // optional - Test helpers
  16. testImplementation "androidx.room:room-testing:$room_version"
  17. // optional - Paging 3 Integration
  18. implementation "androidx.room:room-paging:$room_version"
  19. }

例子

User.java

  1. @Entity
  2. public class User {
  3. @PrimaryKey
  4. private int uid;
  5. @ColumnInfo(name = "first_name")
  6. private String firstName;
  7. @ColumnInfo(name = "last_name")
  8. private String lastName;
  9. // Getters and setters are ignored for brevity,
  10. // but they're required for Room to work.
  11. }

UserDao.java

  1. @Dao
  2. public interface UserDao {
  3. @Query("SELECT * FROM user")
  4. List<User> getAll();
  5. @Query("SELECT * FROM user WHERE uid IN (:userIds)")
  6. List<User> loadAllByIds(int[] userIds);
  7. @Query("SELECT * FROM user WHERE first_name LIKE :first AND "
  8. + "last_name LIKE :last LIMIT 1")
  9. User findByName(String first, String last);
  10. @Insert
  11. void insertAll(User... users);
  12. @Delete
  13. void delete(User user);
  14. }

AppDatabase.java

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

获取AppDatabase实例:

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

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

  1. @Database(entities = {User.class}, version = 1, exportSchema = false)
  2. public abstract class AppDatabase extends RoomDatabase {
  3. private static AppDatabase INSTANCE;
  4. private static final Object sLock = new Object();
  5. public abstract UserDao userDao();
  6. public static AppDatabase getInstance(Context context) {
  7. synchronized (sLock) {
  8. if (INSTANCE == null) {
  9. INSTANCE =
  10. Room.databaseBuilder(context.getApplicationContext(), AppDatabase.class, "roomName.db").allowMainThreadQueries().build();
  11. }
  12. return INSTANCE;
  13. }
  14. }
  15. }

Entity

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

  1. @Entity
  2. class User {
  3. @PrimaryKey
  4. public int id;
  5. public String firstName;
  6. public String lastName;
  7. @Ignore
  8. Bitmap picture;
  9. }

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

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

  1. @Entity(tableName = "users")
  2. class User {
  3. @PrimaryKey
  4. public int id;
  5. @ColumnInfo(name = "first_name")
  6. public String firstName;
  7. @ColumnInfo(name = "last_name")
  8. public String lastName;
  9. @Ignore
  10. Bitmap picture;
  11. }

主键

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

  1. @Entity(primaryKeys = {"firstName", "lastName"})
  2. public class User {
  3. public String firstName;
  4. public String lastName;
  5. }

索引和唯一性

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

  1. @Entity(indices = {@Index("name"),
  2. @Index(value = {"last_name", "address"})})
  3. class User {
  4. @PrimaryKey
  5. public int id;
  6. public String firstName;
  7. public String address;
  8. @ColumnInfo(name = "last_name")
  9. public String lastName;
  10. @Ignore
  11. Bitmap picture;
  12. }

有时候,需要确保某个字段或者多个字段形成的组唯一。可以通过将@Index的unique属性设置为true,来确保唯一性。在下面的例子中,防止first_name和last_name这两列同时具有相同的数据。

  1. @Entity(indices = {@Index(value = {"first_name", "last_name"},
  2. unique = true)})
  3. class User {
  4. @PrimaryKey
  5. public int id;
  6. @ColumnInfo(name = "first_name")
  7. public String firstName;
  8. @ColumnInfo(name = "last_name")
  9. public String lastName;
  10. @Ignore
  11. Bitmap picture;
  12. }

关系

SQLite是关系型数据库,你可以指定不同对象之间的关系。尽管大多数ORM类库允许对象之间互相引用,但Room明确禁止这一点。

尽管不能使用直接关系,Room仍然两个实体之间定义外键。

例如,有另外一个实体Book,你可以使用@ForeignKey注解定义和User之间的关系。

  1. @Entity(foreignKeys = @ForeignKey(entity = User.class,
  2. parentColumns = "id",
  3. childColumns = "user_id"))
  4. class Book {
  5. @PrimaryKey
  6. public int bookId;
  7. public String title;
  8. @ColumnInfo(name = "user_id")
  9. public int userId;
  10. }

外键非常有用,因为当引用的实体发生改变时,你可以指定如何处理。例如,如果@ForeignKey的onDelete属性值为CASCADE,如果删除user,所有具有相同userId的book会被全部删除。

嵌套对象

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

  1. public class User {
  2. @PrimaryKey(autoGenerate = true)
  3.   public int id;
  4. public String firstName;
  5. public String lastName;
  6. //
  7. @Ignore Bitmap picture;
  8. public String street;
  9. public String state;
  10. public String city;
  11. @ColumnInfo(name = "post_code")
  12. public int postCode;
  13. }

创建的表

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

  1. class Address {
  2. public String street;
  3. public String state;
  4. public String city;
  5. @ColumnInfo(name = "post_code")
  6. public int postCode;
  7. }

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

  1. @Entity
  2. class User {
  3. @PrimaryKey(autoGenerate = true)
  4.   public int id;
  5. public String firstName;
  6. public String lastName;
  7. //
  8. @Ignore
  9.   Bitmap picture;
  10. @Embedded
  11. public Address address;
  12. }

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

  1. public class User {
  2. @PrimaryKey(autoGenerate = true)
  3. public int id;
  4. public String firstName;
  5. public String lastName;
  6. @Embedded(prefix = "first")
  7. Address address;
  8. @Embedded(prefix = "second")
  9. AddressTwo addressTwo;
  10. }

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

数据访问对象(DAOs)

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

Insert

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

  1. @Dao
  2. public interface MyDao {
  3. @Insert(onConflict = OnConflictStrategy.REPLACE)
  4. public void insertUsers(User... users);
  5. @Insert
  6. public void insertBothUsers(User user1, User user2);
  7. @Insert
  8. public void insertUsersAndFriends(User user, List<User> friends);
  9. }

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

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

OnConflictStrategy

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

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

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

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

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

Update

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

  1. @Dao
  2. public interface MyDao {
  3. @Update
  4. public void updateUsers(User... users);
  5. }

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

Delete

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

  1. @Dao
  2. public interface MyDao {
  3. @Delete
  4. public void deleteUsers(User... users);
  5. }

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

Query

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

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

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

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

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

  1. @Dao
  2. public interface MyDao {
  3. @Query("SELECT * FROM user")
  4. public User[] loadAllUsers();
  5. }

传入参数

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

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

  1. @Dao
  2. public interface MyDao {
  3. //传入单个参数
  4. @Query("SELECT * FROM user WHERE age > :minAge")
  5. public User[] loadAllUsersOlderThan(int minAge);
  6. }

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

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

  1. @Dao
  2. public interface MyDao {
  3. @Query("SELECT * FROM user WHERE age BETWEEN :minAge AND :maxAge")
  4. public User[] loadAllUsersBetweenAges(int minAge, int maxAge);
  5. @Query("SELECT * FROM user WHERE first_name LIKE :search "
  6. + "OR last_name LIKE :search")
  7. public List<User> findUserWithName(String search);
  8. }

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

  1. @Dao
  2. public interface MyDao {
  3. @Query("SELECT first_name, last_name FROM user WHERE region IN (:regions)")
  4. public List<NameTuple> loadUsersFromRegions(List<String> regions);
  5. }

返回列的子集

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

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

  1. public class NameTuple {
  2. @ColumnInfo(name="first_name")
  3. public String firstName;
  4. @ColumnInfo(name="last_name")
  5. public String lastName;
  6. }

在查询方法中使用该对象

  1. @Dao
  2. public interface MyDao {
  3. @Query("SELECT first_name, last_name FROM user")
  4. public List<NameTuple> loadFullName();
  5. }

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

Observable查询

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

  1. @Dao
  2. public interface MyDao {
  3. @Query("SELECT first_name, last_name FROM user WHERE region IN (:regions)")
  4. public LiveData<List<User>> loadUsersFromRegionsSync(List<String> regions);
  5. }

RxJava的响应式查询

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

  1. @Dao
  2. public interface MyDao {
  3. @Query("SELECT * from user where id = :id LIMIT 1")
  4. public Flowable<User> loadUserById(int id);
  5. // Emits the number of users added to the database.
  6. @Insert
  7. public Maybe<Integer> insertLargeNumberOfUsers(List<User> users);
  8. // Makes sure that the operation finishes successfully.
  9. @Insert
  10. public Completable insertLargeNumberOfUsers(User... users);
  11. /* Emits the number of users removed from the database. Always emits at
  12. least one user. */
  13. @Delete
  14. public Single<Integer> deleteUsers(List<User> users);
  15. }

直接返回Cursor

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

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

查询多个表
  1. @Dao
  2. public interface MyDao {
  3. @Query("SELECT * FROM book "
  4. + "INNER JOIN loan ON loan.book_id = book.id "
  5. + "INNER JOIN user ON user.id = loan.user_id "
  6. + "WHERE user.name LIKE :userName")
  7. public List<Book> findBooksBorrowedByNameSync(String userName);
  8. }

类型转换器

Room支持字符串和基本数据类型以及他们的包装类,但是如果不是基本数据类型,该如何存储呢?比如我们的User对象有个Date类型的字段birthday,我们该如何存储。Room提供了@TypeConverter可以将不可存储的类型转换为Room可以存储的类型。

  1. public class Converters {
  2. @TypeConverter
  3. public static Date fromTimestamp(Long value) {
  4. return value == null ? null : new Date(value);
  5. }
  6. @TypeConverter
  7. public static Long dateToTimestamp(Date date) {
  8. return date == null ? null : date.getTime();
  9. }
  10. }

上面的例子定义了两个方法,Room可以调用dateToTimestamp方法将Date转化为Long类型进行存储,也可以在查询的时候调用fromTimestamp将获取的Long转换为Date对象。

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

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

数据库升级

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

  1. Room.databaseBuilder(getApplicationContext(), MyDb.class, "database-name")
  2. .addMigrations(MIGRATION_1_2, MIGRATION_2_3).build();
  3. static final Migration MIGRATION_1_2 = new Migration(1, 2) {
  4. @Override
  5. public void migrate(SupportSQLiteDatabase database) {
  6. database.execSQL("CREATE TABLE `Fruit` (`id` INTEGER, "
  7. + "`name` TEXT, PRIMARY KEY(`id`))");
  8. }
  9. };
  10. static final Migration MIGRATION_2_3 = new Migration(2, 3) {
  11. @Override
  12. public void migrate(SupportSQLiteDatabase database) {
  13.         database.execSQL("ALTER TABLE Book ADD COLUMN ctime TEXT");
  14. //database.execSQL("ALTER TABLE Book "
  15. // + " ADD COLUMN pub_year INTEGER NOT NULL DEFAULT 0");
  16.         //当添加int 类型数据时,需要添加默认值
  17. }
  18. };

注:当添加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#java

声明:本文内容由网友自发贡献,不代表【wpsshop博客】立场,版权归原作者所有,本站不承担相应法律责任。如您发现有侵权的内容,请联系我们。转载请注明出处:https://www.wpsshop.cn/w/知新_RL/article/detail/745869
推荐阅读
相关标签
  

闽ICP备14008679号