fa-dataability.md 11.1 KB
Newer Older
1
# Data Ability Development
W
wusongqing 已提交
2

W
wusongqing 已提交
3
## When to Use
W
wusongqing 已提交
4

5 6 7 8
A Data ability helps applications manage access to data stored by themselves and other applications. It also provides APIs for sharing data with other applications either on the same device or across devices.

Data ability providers can customize data access-related APIs such as data inserting, deleting, updating, and querying, as well as file opening, and share data with other applications through these open APIs.

W
wusongqing 已提交
9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
## URI Introduction

A Uniform Resource Identifier (URI) is used to identify a specific data item, such as a table in the database or a file on the disk. URIs used in OpenHarmony comply with the commonly used URI standard. A URI consists of the components:

![fa-dataability-uri](figures/fa-dataability-uri.png)

- **scheme**: name of the scheme used by the Data ability. The value is fixed at **dataability**.
- **authority**: device ID. To access data on a remote device, set this component to the ID of the remote device. To access data on the local device, leave this component empty.
- **path**: location of the specific resource to access.
- **query**: query parameters.
- **fragment**: subordinate resources to access.

Example URIs:

- Cross-device communication: **dataability://***device_id***/***com.domainname.dataability.persondata***/***person***/***10*
- Local-device communication: **dataability:///***com.domainname.dataability.persondata***/***person***/***10*

> **NOTE**
G
Gloria 已提交
27
> 
W
wusongqing 已提交
28 29
> In the case of local-device communication, **device_id** is empty, and therefore, there are three slashes (/) after **dataability:**.

W
wusongqing 已提交
30 31
## Available APIs

W
wusongqing 已提交
32
**Table 1** Data ability lifecycle APIs
W
wusongqing 已提交
33 34
|API|Description|
|:------|:------|
W
wusongqing 已提交
35 36 37 38 39 40 41 42 43 44 45 46 47
|onInitialized?(info: AbilityInfo): void|Called during ability initialization to initialize the relational database (RDB).|
|update?(uri: string, valueBucket: rdb.ValuesBucket, predicates: dataAbility.DataAbilityPredicates, callback: AsyncCallback\<number>): void|Updates data in the database.|
|query?(uri: string, columns: Array\<string>, predicates: dataAbility.DataAbilityPredicates, callback: AsyncCallback\<ResultSet>): void|Queries data in the database.|
|delete?(uri: string, predicates: dataAbility.DataAbilityPredicates, callback: AsyncCallback\<number>): void|Deletes one or more data records from the database.|
|normalizeUri?(uri: string, callback: AsyncCallback\<string>): void|Normalizes the URI. A normalized URI applies to cross-device use, persistence, backup, and restore. When the context changes, it ensures that the same data item can be referenced.|
|batchInsert?(uri: string, valueBuckets: Array\<rdb.ValuesBucket>, callback: AsyncCallback\<number>): void|Inserts multiple data records into the database.|
|denormalizeUri?(uri: string, callback: AsyncCallback\<string>): void|Converts a normalized URI generated by **normalizeUri** into a denormalized URI.|
|insert?(uri: string, valueBucket: rdb.ValuesBucket, callback: AsyncCallback\<number>): void|Inserts a data record into the database.|
|openFile?(uri: string, mode: string, callback: AsyncCallback\<number>): void|Opens a file.|
|getFileTypes?(uri: string, mimeTypeFilter: string, callback: AsyncCallback\<Array\<string>>): void|Obtains the MIME type of a file.|
|getType?(uri: string, callback: AsyncCallback\<string>): void|Obtains the MIME type matching the data specified by the URI.|
|executeBatch?(ops: Array\<DataAbilityOperation>, callback: AsyncCallback\<Array\<DataAbilityResult>>): void|Operates data in the database in batches.|
|call?(method: string, arg: string, extras: PacMap, callback: AsyncCallback\<PacMap>): void|Calls a custom API.|
W
wusongqing 已提交
48 49 50 51


## How to Develop
### Creating a Data Ability
52

W
wusongqing 已提交
53
1. To meet the basic requirements of the database storage service, implement the **Insert**, **Query**, **Update**, and **Delete** APIs in the **Data** class. The **BatchInsert** and **ExecuteBatch** APIs have already implemented the traversal logic, but not batch data processing.
54

W
wusongqing 已提交
55
    The following code snippet shows how to create a Data ability:
56 57

   ```javascript
W
wusongqing 已提交
58 59 60 61 62 63 64 65
    import dataAbility from '@ohos.data.dataAbility'
    import dataRdb from '@ohos.data.rdb'

    const TABLE_NAME = 'book'
    const STORE_CONFIG = { name: 'book.db' }
    const SQL_CREATE_TABLE = 'CREATE TABLE IF NOT EXISTS book(id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, introduction TEXT NOT NULL)'
    let rdbStore: dataRdb.RdbStore = undefined

66
    export default {
W
wusongqing 已提交
67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83
    onInitialized(abilityInfo) {
        console.info('DataAbility onInitialized, abilityInfo:' + abilityInfo.bundleName)
        dataRdb.getRdbStore(STORE_CONFIG, 1, (err, store) => {
            console.info('DataAbility getRdbStore callback')
            store.executeSql(SQL_CREATE_TABLE, [])
            rdbStore = store
        });
    },
    insert(uri, valueBucket, callback) {
        console.info('DataAbility insert start')
        rdbStore.insert(TABLE_NAME, valueBucket, callback)
    },
    batchInsert(uri, valueBuckets, callback) {
        console.info('DataAbility batch insert start')
        for (let i = 0;i < valueBuckets.length; i++) {
            console.info('DataAbility batch insert i=' + i)
            if (i < valueBuckets.length - 1) {
W
wusongqing 已提交
84
                rdbStore.insert(TABLE_NAME, valueBuckets[i], (err: any, num: number) => {
W
wusongqing 已提交
85 86 87 88
                    console.info('DataAbility batch insert ret=' + num)
                })
            } else {
                rdbStore.insert(TABLE_NAME, valueBuckets[i], callback)
89 90
            }
        }
W
wusongqing 已提交
91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106
    },
    query(uri, columns, predicates, callback) {
        console.info('DataAbility query start')
        let rdbPredicates = dataAbility.createRdbPredicates(TABLE_NAME, predicates)
        rdbStore.query(rdbPredicates, columns, callback)
    },
    update(uri, valueBucket, predicates, callback) {
        console.info('DataAbilityupdate start')
        let rdbPredicates = dataAbility.createRdbPredicates(TABLE_NAME, predicates)
        rdbStore.update(valueBucket, rdbPredicates, callback)
    },
    delete(uri, predicates, callback) {
        console.info('DataAbilitydelete start')
        let rdbPredicates = dataAbility.createRdbPredicates(TABLE_NAME, predicates)
        rdbStore.delete(rdbPredicates, callback)
    }
107 108 109
    };
   ```

W
wusongqing 已提交
110
2. Configure the submodule.
111

W
wusongqing 已提交
112 113 114 115 116 117
   | JSON Field| Description                                                    |
   | ------------ | ------------------------------------------------------------ |
   | "name"       | Ability name, corresponding to the **Data** class name derived from **Ability**.                    |
   | "type"       | Ability type, which is **Data** for a Data ability.                |
   | "uri"        | URI used for communication.                                             |
   | "visible"    | Whether the Data ability is visible to other applications. When this parameter is set to **true**, the Data ability can communicate with other applications.|
118

W
wusongqing 已提交
119
   **config.json configuration example**
120

W
wusongqing 已提交
121 122
   ```json
   "abilities":[{
W
wusongqing 已提交
123 124 125 126 127 128 129 130 131
       "srcPath": "DataAbility",
       "name": ".DataAbility",
       "icon": "$media:icon",
       "srcLanguage": "ets",
       "description": "$string:description_dataability",
       "type": "data",
       "visible": true,
       "uri": "dataability://ohos.samples.etsdataability.DataAbility"
    }]
W
wusongqing 已提交
132 133 134 135 136 137 138 139 140
   ```

### Accessing a Data ability
#### Development Preparations

Import the basic dependency packages and obtain the URI string for communicating with the Data submodule.

The basic dependency packages include:
- @ohos.ability.featureAbility
G
Gloria 已提交
141
- @ohos.data.dataAbility
W
wusongqing 已提交
142 143 144
- @ohos.data.rdb

#### Data Ability API Development
145 146


W
wusongqing 已提交
147 148 149 150 151
1. Create a Data ability helper.

   For details about the APIs provided by **DataAbilityHelper**, see [DataAbilityHelper Module](../reference/apis/js-apis-dataAbilityHelper.md).
   ```js
   // Different from the URI defined in the config.json file, the URI passed in the parameter has an extra slash (/), because there is a DeviceID parameter between the second and the third slash (/).
W
wusongqing 已提交
152 153 154
   import featureAbility from '@ohos.ability.featureAbility'
   import ohos_data_ability from '@ohos.data.dataAbility'
   import ohos_data_rdb from '@ohos.data.rdb'
G
Gloria 已提交
155

W
wusongqing 已提交
156 157
   var urivar = "dataability:///com.ix.DataAbility"
   var DAHelper = featureAbility.acquireDataAbilityHelper(
158
    urivar
W
wusongqing 已提交
159 160 161 162 163 164 165 166 167 168 169 170 171
   );
   ```
2. Construct RDB data.
   ```js
   var valuesBucket = {"name": "gaolu"}
   var da = new ohos_data_ability.DataAbilityPredicates()
   var valArray =new Array("value1");
   var cars = new Array({"batchInsert1" : "value1",});
   ```
3. Use **insert** to insert data to the Data submodule.
   ```js
   // Callback mode:
   DAHelper.insert(
172 173 174
    urivar,
    valuesBucket,
    (error, data) => {
W
wusongqing 已提交
175
        console.log("DAHelper insert result: " + data)
176
    }
W
wusongqing 已提交
177 178 179 180 181 182
   );
   ```
   
   ```js
   // Promise mode:
   var datainsert = await DAHelper.insert(
183 184
    urivar,
    valuesBucket
W
wusongqing 已提交
185 186 187 188 189 190
   );
   ```
4. Use **delete** to delete data from the Data submodule.
   ```js
   // Callback mode:
   DAHelper.delete(
191 192 193
    urivar,
    da,
    (error, data) => {
W
wusongqing 已提交
194
        console.log("DAHelper delete result: " + data)
195
    }
W
wusongqing 已提交
196 197 198 199 200 201
   );
   ```
   
   ```js
   // Promise mode:
   var datadelete = await DAHelper.delete(
202 203
    urivar,
    da,
W
wusongqing 已提交
204 205 206 207 208 209
   );
   ```
5. Use **update** to update data in the Data submodule.
   ```js
   // Callback mode:
   DAHelper.update(
210 211 212 213
    urivar
    valuesBucket,
    da,
    (error, data) => {
W
wusongqing 已提交
214
        console.log("DAHelper update result: " + data)
215
    }
W
wusongqing 已提交
216 217 218 219 220 221
   );
   ```
   
   ```js
   // Promise mode:
   var dataupdate = await DAHelper.update(
222 223 224
    urivar,
    valuesBucket,
    da,
W
wusongqing 已提交
225 226 227 228 229 230
   );
   ```
6. Use **query** to query data in the Data submodule.
   ```js
   // Callback mode:
   DAHelper.query(
231 232 233 234
    urivar,
    valArray,
    da,
    (error, data) => {
W
wusongqing 已提交
235
        console.log("DAHelper query result: " + data)
236
    }
W
wusongqing 已提交
237 238 239 240 241 242
   );
   ```
   
   ```js
   // Promise mode:
   var dataquery = await DAHelper.query(
243 244 245
    urivar,
    valArray,
    da
W
wusongqing 已提交
246 247 248 249 250 251
   );
   ```
7. Use **batchInsert** to insert data in batches to the Data submodule.
   ```js
   // Callback mode:
   DAHelper.batchInsert(
252 253 254
    urivar,
    cars,
    (error, data) => {
W
wusongqing 已提交
255
        console.log("DAHelper batchInsert result: " + data)
256
    }
W
wusongqing 已提交
257 258 259 260 261 262
   );
   ```
   
   ```js
   // Promise mode:
   var databatchInsert = await DAHelper.batchInsert(
263 264
    urivar,
    cars
W
wusongqing 已提交
265 266 267 268 269 270
   );
   ```
8. Use **executeBatch** to process data in batches in the Data submodule.
   ```js
   // Callback mode:
   DAHelper.executeBatch(
271 272 273 274 275 276 277 278
    urivar,
    [
        {
            uri: urivar,
            type: featureAbility.DataAbilityOperationType.TYPE_INSERT,
            valuesBucket: {"executeBatch" : "value1",},
            predicates: da,
            expectedCount:0,
W
wusongqing 已提交
279
            predicatesBackReferences: null,
280 281 282 283
            interrupted:true,
        }
    ],
    (error, data) => {
W
wusongqing 已提交
284
        console.log("DAHelper executeBatch result: " + data)
285
    }
W
wusongqing 已提交
286 287 288 289 290 291
   );
   ```
   
   ```js
   // Promise mode:
   var dataexecuteBatch = await DAHelper.executeBatch(
292 293 294 295 296 297 298 299 300 301 302
    urivar,
    [
        {
            uri: urivar,
            type: featureAbility.DataAbilityOperationType.TYPE_INSERT,
            valuesBucket:
            {
                "executeBatch" : "value1",
            },
            predicates: da,
            expectedCount:0,
W
wusongqing 已提交
303
            predicatesBackReferences: null,
304 305 306
            interrupted:true,
        }
    ]
W
wusongqing 已提交
307 308
   );
   ```