鸿蒙OS 对象关系映射数据库开发指导

场景介绍

对象关系映射数据库适用于开发者使用的数据可以分解为一个或多个对象，且需要对数据进行增删改查等操作，但是不希望编写过于复杂的 SQL 语句的场景。

该对象关系映射数据库的实现是基于关系型数据库，除了数据库版本升降级等场景外，操作对象关系映射数据库一般不需要编写 SQL 语句，但是仍然要求使用者对于关系型数据库的基本概念有一定的了解。

开发能力介绍

对象关系映射数据库目前可以支持数据库和表的创建，对象数据的增删改查、对象数据变化回调、数据库升降级和备份等功能。

数据库和表的创建

1. 创建数据库。开发者需要定义一个表示数据库的类，继承 OrmDatabase，再通过 @Database 注解内的 entities 属性指定哪些数据模型类属于这个数据库。

属性：

• version：数据库版本号。
• entities：数据库内包含的表。

1. 创建数据表。开发者可通过创建一个继承了OrmObject 并用 @Entity 注解的类，获取数据库实体对象，也就是表的对象。

属性：

• tableName：表名。
• primaryKeys：主键名，一个表里只能有一个主键，一个主键可以由多个字段组成。
• foreignKeys：外键列表。
• indices：索引列表。

接口名称	描述
@Database	被 @Database注解且继承了 OrmDatabase 的类对应数据库类。
@Entity	被 @Entity注解且继承了 OrmObject 的类对应数据表类。
@Column	被 @Column 注解的变量对应数据表的字段。
@PrimaryKey	被 @PrimaryKey 注解的变量对应数据表的主键。
@ForeignKey	被 @ForeignKey 注解的变量对应数据表的外键。
@Index	被 @Index 注解的内容对应数据表索引的属性。

数据库的加密

对象关系映射数据库提供数据库加密的能力，创建数据库时传入指定密钥、创建加密数据库，后续打开加密数据库时，需要传入正确密钥。

类名	接口名	描述
OrmConfig.Builder	Builder setEncryptKey(byte[] encryptKey)	为数据库配置类设置数据库加密密钥，创建或打开数据库时传入包含数据库加密密钥的配置类，即可创建或打开加密数据库。

对象数据的增删改查

通过对象数据操作接口，开发者可以对对象数据进行增删改查操作。

类名	接口名称	描述
OrmContext	<T extends OrmObject> boolean insert(T object)	添加方法。
OrmContext	<T extends OrmObject> boolean update(T object)	更新方法。
OrmContext	<T extends OrmObject> List<T> query(OrmPredicates predicates)	查询方法。
OrmContext	<T extends OrmObject> boolean delete(T object)	删除方法。
OrmContext	<T extends OrmObject> OrmPredicates where(Class<T> clz)	设置谓词方法。

对象数据的变化观察者**设置**

通过使用对象数据操作接口，开发者可以在某些数据上设置观察者，接收数据变化的通知。

类名	接口名称	描述
OrmContext	void registerStoreObserver(String alias, OrmObjectObserver observer)	注册数据库变化回调。
OrmContext	void registerContextObserver(OrmContext watchedContext, OrmObjectObserver observer)	注册上下文变化回调。
OrmContext	void registerEntityObserver(String entityName, OrmObjectObserver observer)	注册数据库实体变化回调。
OrmContext	void registerObjectObserver(OrmObject ormObject, OrmObjectObserver observer)	注册对象变化回调。

数据库的升降级

通过调用数据库升降级接口，开发者可以将数据库切换到不同的版本。

类名	接口名称	描述
OrmMigration	public void onMigrate(int beginVersion, int endVersion)	数据库版本升降级接口。

数据库的备份恢复

开发者可以将当前数据库的数据进行备份，在必要的时候进行数据恢复。

类名	接口名称	描述
OrmContext	boolean backup(String destPath)	数据库备份接口。
OrmContext	boolean restore(String srcPath);	数据库恢复备份接口。

开发步骤

1. 配置“build.gradle”文件。

• 如果使用注解处理器的模块为“com.huawei.ohos.hap”模块，则需要在模块的“build.gradle”文件的“ohos”节点中添加以下配置：

     compileOptions{            annotationEnabled true    } 

• 如果使用注解处理器的模块为“com.huawei.ohos.library”模块，则需要在模块的“build.gradle”文件的“dependencies”节点中配置注解处理器。查看“orm_annotations_java.jar”、“orm_annotations_processor_java.jar” 、“javapoet_java.jar”

这3个 jar 包在 HUAWEI SDK 中的对应目录，并将目录的这三个 jar 包导进来。

     dependencies {
         compile files("orm_annotations_java.jar 的路径","orm_annotations_processor_java.jar 的路径","javapoet_java.jar 的路径")
         annotationProcessor files("orm_annotations_java.jar 的路径","orm_annotations_processor_java.ja 的路径","javapoet_java.jar 的路径")
     }

• 如果使用注解处理器的模块为“java-library”模块，则需要在模块的“build.gradle”文件的“dependencies”节点中配置注解处理器，并导入“ohos.jar”。

     dependencies {
         compile files("ohos.jar 的路径","orm_annotations_java.jar 的路径","orm_annotations_processor_java.jar 的路径","javapoet_java.jar 的路径")     
         annotationProcessor files("orm_annotations_java.jar 的路径","orm_annotations_processor_java.jar 的路径","javapoet_java.jar 的路径")
     }

1. 构造数据库，即创建数据库类并配置对应的属性。

例如，定义了一个数据库类 BookStore.java，数据库包含了“User”，"Book"，"AllDataType"三个表，版本号为 “1”。数据库类的 getVersion 方法和 getHelper 方法不需要实现，直接将数据库类设为虚类即可。

   @Database(entities = {User.class, Book.class, AllDataType.class}, version = 1) 
   public abstract class BookStore extends OrmDatabase { 
   }

1. 构造数据表，即创建数据库实体类并配置对应的属性（如对应表的主键，外键等）。数据表必须与其所在的数据库在同一个模块中。

例如，定义了一个实体类 User.java，对应数据库内的表名为“user”；indices 为“firstName”和“lastName”两个字段建立了复合索引“name_index”，并且索引值是唯一的；“ignoreColumns”表示该字段不需要添加到“user”表的属性中。

   @Entity(tableName = "user", ignoredColumns = {"ignoreColumn1", "ignoreColumn2"},
       indices = {@Index(value = {"firstName", "lastName"}, name = "name_index", unique = true)}) 
   public class User extends OrmObject { 
       // 此处将userId设为了自增的主键。注意只有在数据类型为包装类型时，自增主键才能生效。
       @PrimaryKey(autoGenerate = true) 
       private Integer userId;   
       private String firstName;   
       private String lastName;   
       private int age;   
       private double balance;   
       private int ignoreColumn1; 
       private int ignoreColumn2; 

    
       // 开发者自行添加字段的getter和setter 方法。 
   }

说明

示例中的 getter & setter 的方法名为小驼峰格式，除了手写方法，IDE 中包含自动生成 getter 和setter 方法的 Generate 插件。

• 当变量名的格式类似“firstName”时，getter 和 setter 方法名应为“getFirstName”和“setFirstName”。
• 当变量名的格式类似“mAge”，即第一个字母小写，第二个字母大写的格式时，getter 和 setter 方法名应为“getmAge”和“setmAge”。
• 当变量名格式类似“x”，即只有一个字母时， getter 和 setter 方法名应为“getX”和“setX”。

变量为 boolean 类型时，上述规则仍然成立，即“isFirstName”，“ismAge”，“isX”。

1. 使用对象数据操作接口 OrmContext 创建数据库。

例如，通过对象数据操作接口 OrmContext，创建一个别名为“BookStore”，数据库文件名为“BookStore.db”的数据库。如果数据库已经存在，执行以下代码不会重复创建。通过 context.getDatabaseDir()可以获取创建的数据库文件所在的目录。

   DatabaseHelper helper = new DatabaseHelper(context); // context入参类型为ohos.app.Context，注意不要使用slice.getContext()来获取context，请直接传入slice，否则会出现找不到类的报错。
   OrmContext context = helper.getOrmContext("BookStore", "BookStore.db", BookStore.class); 

1. （可选）数据库升降级。如果开发者有多个版本的数据库，通过设置数据库版本迁移类可以实现数据库版本升降级。

数据库版本升降级的调用示例如下。其中 BookStoreUpgrade 类也是一个继承了 OrmDatabase 的数据库类，与 BookStore 类的区别在于配置的版本号不同。

   OrmContext context = helper.getOrmContext("BookStore", "BookStore.db", BookStoreUpgrade.class, new TestOrmMigration32(), new TestOrmMigration23(), new TestOrmMigration12(), new TestOrmMigration21());

TestOrmMigration12 的实现示例如下：

   private static class TestOrmMigration12 extends OrmMigration {
       // 此处用于配置数据库版本迁移的开始版本和结束版本，super(startVersion, endVersion)即数据库版本号从1升到2。
       public TestOrmMigration12() {super(1, 2); }
       @Override    
       public void onMigrate(RdbStore store) {        
           store.executeSql("ALTER TABLE `Book` ADD COLUMN `addColumn12` INTEGER");   
       }
   }

说明

数据库版本迁移类的起始版本和结束版本必须是连续的。

• 如果 BookStoreUpgrad e类的版本号配置为“2”，而当前 BookStore.db 的实际版本号为“1”时，TestOrmMigration12 类的 onMigrate 方法会自动被调用。开发者可在 onMigrate 方法中填写升级需要执行的 sql 语句。
• 如果 BookStoreUpgrade 的类版本号配置为“3”，而当前 BookStore.db 的实际版本号为“1”时，TestOrmMigration12， TestOrmMigration23 的 onMigrate 方法会自动被调用完成数据库升级。数据库版本降级同理。

1. 使用对象数据操作接口 OrmContext 对数据库进行增删改查、注册观察者、备份数据库等。

• 增加数据。例如，在数据库的名为“user”的表中，新建一个 User 对象并设置对象的属性。直接传入 OrmObject 对象的增加接口，只有在 flush() 接口被调用后才会持久化到数据库中。

     User user = new User(); 
     user.setFirstName("Zhang"); 
     user.setLastName("San"); 
     user.setAge(29); 
     user.setBalance(100.51); 
     boolean isSuccessed = context.insert(user); 
     isSuccessed = context.flush(); 

• 更新或删除数据，分为两种情况：

• 通过直接传入 OrmObject 对象的接口来更新数据，需要先从表中查到需要更新的 User 对象列表，然后修改对象的值，再调用更新接口持久化到数据库中。删除数据与更新数据的方法类似，只是不需要更新对象的值。

例如，更新“user”表中age为“29”的行，需要先查找“user”表中对应数据，得到一个 User 的列表。然后选择列表中需要更新的 User 对象（如第 0 个对象），设置需要更新的值，并调用 update 接口传入被更新的 User 对象。最后调用 flush 接口持久化到数据库中。

       // 更新数据
       OrmPredicates predicates = context.where(User.class);
       predicates.equalTo("age",29);
       List<User> users = context.query(predicates);
       User user = users.get(0);
       user.setFirstName("Li");
       context.update(user);
       context.flush();

        
       // 删除数据
       OrmPredicates predicates = context.where(User.class);
       predicates.equalTo("age",29);
       List<User> users = context.query(predicates);
       User user = users.get(0);
       context.delete(user);
       context.flush();

• 通过传入谓词的接口来更新和删除数据，方法与 OrmObject 对象的接口类似，只是无需 flush 就可以持久化到数据库中。

       ValuesBucket valuesBucket = new ValuesBucket();
       valuesBucket.putInteger("age", 31);
       valuesBucket.putString("firstName", "ZhangU");
       valuesBucket.putString("lastName", "SanU");
       valuesBucket.putDouble("balance", 300.51);
       OrmPredicates update = context.where(User.class).equalTo("userId", 1);
       context.update(update, valuesBucket);

• 查询数据。在数据库的“user”表中查询lastName为“San”的 User 对象列表，示例如下：

     OrmPredicates query = context.where(User.class).equalTo("lastName", "San"); 
     List<User> users = context.query(query);

• 注册观察者。

     // 定义一个观察者类。
     private class MyOrmObjectObserver implements OrmObjectObserver {
         @Override    
         public void onChange(OrmContext changeContext,AllChangeToTarget subAllChange {
             // 用户可以在此处定义观察者行为
         }
     }

      
     // 调用registerEntityObserver方法注册一个观察者observer。
     MyOrmObjectObserver observer = new MyOrmObjectObserver();
     context.registerEntityObserver("user", observer);

      
     // 当以下方法被调用，并flush成功时，观察者observer的onChange方法会被触发。其中，方法的入参必须为User类的对象。
     public <T extends OrmObject> boolean insert(T object)
     public <T extends OrmObject> boolean update(T object)
     public <T extends OrmObject> boolean delete(T object)

• 备份数据库。其中原数据库名为“OrmBackUp.db”，备份数据库名为“OrmBackup001.db”。

     OrmContext context = helper.getObjectContext("OrmBackup", "OrmBackup.db", BookStore.class);
     context.backup("OrmBackup001.db");
     context.close();

1. 删除数据库，例如删除 OrmBackup.db。

   helper.deleteRdbStore("OrmBackup.db");