基本概念
使用Data模板的Ability有助于应用管理其自身和其他应用存储数据的访问,并提供与其他应用共享数据的方法。Data既可用于同设备不同应用的数据共享,也支持跨设备不同应用的数据共享。
数据的存放形式多样,可以是数据库,也可以是磁盘上的文件。Data对外提供对数据的增、删、改、查,以及打开文件等接口,这些接口的具体实现由开发者提供。
Data的提供方和使用方都通过URI(Uniform Resource Identifier)来标识一个具体的数据,例如数据库中的某个表或磁盘上的某个文件。HarmonyOS的URI仍基于URI通用标准,格式如下:.
- scheme:协议方案名,固定为“dataability”,代表Data Ability所使用的协议类型。
- authority:设备ID,如果为跨设备场景,则为目的设备的IP地址;如果为本地设备场景,则不需要填写。
- path:资源的路径信息,代表特定资源的位置信息。
- query:查询参数。
- fragment:可以用于指示要访问的子资源。
URI示例:
- 跨设备场景:dataability://device_id/com.huawei.dataability.persondata/person/10
- 本地设备:dataability:///com.huawei.dataability.persondata/person/10
访问Data
开发者可以通过DataAbilityHelper类来访问当前应用或其他应用提供的共享数据。DataAbilityHelper作为客户端,与提供方的Data进行通信。Data接收到请求后,执行相应的处理,并返回结果。DataAbilityHelper提供了一系列与Data Ability对应的方法。其使用步骤为:
对于访问权限的声明,一般在配置文件中实现:
"reqPermissions": [
{
"name": "com.example.myapplication5.DataAbility.DATA"
}
]
DataAbilityHelper为开发者提供了creator()方法来创建DataAbilityHelper实例。该方法为静态方法,有多个重载。最常见的方法是通过传入一个context对象来创建DataAbilityHelper对象。
获取helper对象示例:
DataAbilityHelper helper = DataAbilityHelper.creator(this);
DataAbilityHelper为开发者提供了一系列的接口来访问不同类型的数据(文件、数据库等)。
-
访问文件
DataAbilityHelper为开发者提供了FileDescriptor openFile(Uri uri, String mode)方法来操作文件。此方法需要传入两个参数,其中uri用来确定目标资源路径,mode用来指定打开文件的方式,可选方式包含“r”(读), “w”(写), “rw”(读写),“wt”(覆盖写),“wa”(追加写),“rwt”(覆盖写且可读)。该方法返回一个目标文件的FD(文件描述符),把文件描述符封装成流,开发者就可以对文件流进行自定义处理。
访问文件示例:
// 读取文件描述符 FileDescriptor fd = helper.openFile(uri, "r"); FileInputStream fis = new FileInputStream(fd);
-
访问数据库
DataAbilityHelper为开发者提供了增、删、改、查以及批量处理等方法来操作数据库。
方法 | 功能描述 |
---|---|
ResultSet query(Uri uri, String[] columns, DataAbilityPredicates predicates) | 查询数据库 |
int insert(Uri uri, ValuesBucket value) | 向数据库中插入单条数据 |
int batchInsert(Uri uri, ValuesBucket[] values) | 向数据库中插入多条数据 |
int delete(Uri uri, DataAbilityPredicates predicates) | 删除一条或多条数据 |
int update(Uri uri, ValuesBucket value, DataAbilityPredicates predicates) | 更新数据库 |
DataAbilityResult[] executeBatch(ArrayList< DataAbilityOperation> operations) | 批量操作数据库 |
这些方法的使用说明如下:
- query()
查询方法,其中uri为目标资源路径,columns为想要查询的字段。开发者的查询条件可以通过DataAbilityPredicates来构建。查询用户表中id在101-103之间的用户,并把结果打印出来,代码示例如下:
DataAbilityHelper helper = DataAbilityHelper.creator(this);
// 构造查询条件
DataAbilityPredicates predicates = new DataAbilityPredicates();
predicates.between("userId", 101, 103);
// 进行查询
ResultSet resultSet = helper.query(uri,columns,predicates);
// 处理结果
resultSet.goToFirstRow();
do{
// 在此处理ResultSet中的记录;
}while(resultSet.goToNextRow());
- insert()
新增方法,其中uri为目标资源路径,ValuesBucket为要新增的对象。插入一条用户信息的代码示例如下:
DataAbilityHelper helper = DataAbilityHelper.creator(this);
// 构造插入数据
ValuesBucket valuesBucket = new ValuesBucket();
valuesBucket.putString("name", "Tom");
valuesBucket.putInteger("age", 12);
helper.insert(uri, valuesBucket);
- batchInsert()
批量插入方法,和insert()类似。批量插入用户信息的代码示例如下:
DataAbilityHelper helper = DataAbilityHelper.creator(this);
// 构造插入数据
ValuesBucket[] values = new ValuesBucket[2];
value[0] = new ValuesBucket();
value[0].putString("name", "Tom");
value[0].putInteger("age", 12);
value[1] = new ValuesBucket();
value[1].putString("name", "Tom1");
value[1].putInteger("age", 16);
helper.batchInsert(uri, values);
- delete()
删除方法,其中删除条件可以通过DataAbilityPredicates来构建。删除用户表中id在101-103之间的用户,代码示例如下:
DataAbilityHelper helper = DataAbilityHelper.creator(this);
// 构造删除条件
DataAbilityPredicates predicates = new DataAbilityPredicates();
predicates.between("userId", 101,103);
helper.delete(uri,predicates);
- update()
更新方法,更新数据由ValuesBucket传入,更新条件由DataAbilityPredicates来构建。更新id为102的用户,代码示例如下:
DataAbilityHelper helper = DataAbilityHelper.creator(this);
// 构造更新条件
DataAbilityPredicates predicates = new DataAbilityPredicates();
predicates.equalTo("userId",102);
// 构造更新数据
ValuesBucket valuesBucket = new ValuesBucket();
valuesBucket.putString("name", "Tom");
valuesBucket.putInteger("age", 12);
helper.update(uri, valuesBucket, predicates);
- executeBatch()
此方法用来执行批量操作。DataAbilityOperation中提供了设置操作类型、数据和操作条件的方法,开发者可自行设置自己要执行的数据库操作。插入多条数据的代码示例如下:
DataAbilityHelper helper = DataAbilityHelper.creator(abilityObj, insertUri);
// 构造批量操作
ValuesBucket value1 = initSingleValue();
DataAbilityOperation opt1 = DataAbilityOperation.newInsertBuilder(insertUri).withValuesBucket(value1).build();
ValuesBucket value2 = initSingleValue2();
DataAbilityOperation opt2 = DataAbilityOperation.newInsertBuilder(insertUri).withValuesBucket(value2).build();
ArrayList<DataAbilityOperation> operations = new ArrayList<DataAbilityOperation>();
operations.add(opt1);
operations.add(opt2);
DataAbilityResult[] result = helper.executeBatch(insertUri, operations);
创建Data
使用Data模板的Ability形式仍然是Ability,因此,开发者需要为应用添加一个或多个Ability的子类,来提供程序与其他应用之间的接口。Data为结构化数据和文件提供了不同API接口供用户使用,因此,开发者需要首先确定好使用何种类型的数据。
确定数据存储方式
确定数据的存储方式,Data支持以下两种数据形式:
- 文件数据:如文本、图片、音乐等。
- 结构化数据:如数据库等。
UserDataAbility接收其他应用发送的请求,提供外部程序访问的入口,从而实现应用间的数据访问。Data提供了文件存储和数据库存储两组接口供用户使用。
文件存储
开发者需要在Data中重写FileDescriptor openFile(Uri uri, String mode)方法来操作文件:uri为客户端传入的请求目标路径;mode为开发者对文件的操作选项,可选方式包含“r”(读), “w”(写), “rw”(读写)等。
MessageParcel类提供了一个静态方法,用于获取MessageParcel实例。通过dupFileDescriptor()函数复制待操作文件流的文件描述符,并将其返回,供远端应用使用。
示例:根据传入的uri打开对应的文件
// 创建messageParcel
MessageParcel messageParcel = MessageParcel.obtain();
File file = new File(uri.getDecodedPathList().get(1));
if (mode == null || !"rw".equals(mode)) {
file.setReadOnly();
}
FileInputStream fileIs = new FileInputStream(file);
FileDescriptor fd = fileIs.getFD();
// 绑定文件描述符
return messageParcel.dupFileDescriptor(fd);
数据库存储
- 首先需要初始化数据库连接。
系统会在应用启动时调用onStart()方法创建Data实例。在此方法中,开发者应该创建数据库连接,并获取连接对象,以便后续和数据库进行操作。为了避免影响应用启动速度,开发者应当尽可能将非必要的耗时任务推迟到使用时执行,而不是在此方法中执行所有初始化。
示例:初始化的时候连接数据库
private static final String DATABASE_NAME ="UserDataAbility.db";
private static final String DATABASE_NAME_ALIAS = "UserDataAbility";
private OrmContext ormContext = null;
@Override
public void onStart(Intent intent) {
super.onStart(intent);
DatabaseHelper manager = new DatabaseHelper(this);
ormContext = manager.getOrmContext(DATABASE_NAME_ALIAS, DATABASE_NAME, BookStore.class);
}
- 然后是编写数据库操作方法。
Ability定义了6个方法供用户处理对数据库表数据的增删改查。这6个方法在Ability中已默认实现,开发者可按需重写。就是上面的六个方法。
注册UserDataAbility
和Service类似,开发者必须在配置配置文件中注册Data。并且配置以下属性:
- type: 类型设置为data
- uri: 对外提供的访问路径,全局唯一
- permissions: 访问该data ability时需要申请的访问权限
{
"name": ".UserDataAbility",
"type": "data",
"visible": true,
"uri": "dataability://com.example.myapplication5.DataAbilityTest",
"permissions": [
"com.example.myapplication5.DataAbility.DATA"
]
}