The distributed data objects allow data across devices to be processed like local variables by shielding complex data interaction between devices. For the devices that form a Super Device, when data in the distributed data object of an application is added, deleted, or modified on a device, the data for the same application is also updated on the other devices. The devices can listen for the data changes and online and offline status of other devices. The distributed data objects support basic data types, such as number, string, and Boolean, as well as complex data types, such as array and nested basic types.
Distributed data objects allow data traversing across devices to be processed like local variables by shielding complex data interaction between devices. For the devices that form a Super Device, when data in the distributed data object of an application is added, deleted, or modified on a device, the data for the same application is also updated on the other devices. The devices can listen for data changes and online and offline status changes of other devices.
The distributed data objects support basic data types, such as number, string, and Boolean, as well as complex data types, such as array and nested basic types.
## Available APIs
## Available APIs
...
@@ -15,7 +17,7 @@ Call **createDistributedObject()** to create a distributed data object instance.
...
@@ -15,7 +17,7 @@ Call **createDistributedObject()** to create a distributed data object instance.
**Table 1** API for creating a distributed data object instance
**Table 1** API for creating a distributed data object instance
| Package| API| Description|
| Package | API | Description |
| -------- | -------- | -------- |
| -------- | -------- | -------- |
| ohos.data.distributedDataObject| createDistributedObject(source: object): DistributedObject | Creates a distributed data object instance for data operations.<br>- **source**: attributes of the **distributedObject** set.<br>- **DistributedObject**: returns the distributed object created.|
| ohos.data.distributedDataObject| createDistributedObject(source: object): DistributedObject | Creates a distributed data object instance for data operations.<br>- **source**: attributes of the **distributedObject** set.<br>- **DistributedObject**: returns the distributed object created.|
...
@@ -24,7 +26,7 @@ Call **createDistributedObject()** to create a distributed data object instance.
...
@@ -24,7 +26,7 @@ Call **createDistributedObject()** to create a distributed data object instance.
Call **genSessionId()** to generate a session ID randomly. The generated session ID can be used to set the session ID of a distributed data object.
Call **genSessionId()** to generate a session ID randomly. The generated session ID can be used to set the session ID of a distributed data object.
**Table 2** API for generating a session ID randomly
**Table 2** API for generating a session ID randomly
| Package| API| Description|
| Package | API | Description |
| -------- | -------- | -------- |
| -------- | -------- | -------- |
| ohos.data.distributedDataObject| genSessionId(): string | Generates a session ID, which can be used as the session ID of a distributed data object.|
| ohos.data.distributedDataObject| genSessionId(): string | Generates a session ID, which can be used as the session ID of a distributed data object.|
...
@@ -39,20 +41,20 @@ Call **setSessionId()** to set a session ID for a distributed data object. The s
...
@@ -39,20 +41,20 @@ Call **setSessionId()** to set a session ID for a distributed data object. The s
### Observing Data Changes
### Observing Data Changes
Call **on()** to subscribe to data changes of a distributed data object. When the data changes, a callback will be invoked to return the data changes. You can use **off()** to unsubscribe from the data changes.
Call **on()** to subscribe to data changes of a distributed data object. In the case of data change, a callback will be invoked to return the data changes. You can use **off()** to unsubscribe from the data changes.
**Table 4** APIs for observing data changes of a distributed data object
**Table 4** APIs for observing data changes of a distributed data object
| Class| API| Description|
| Class | API | Description |
| -------- | -------- | -------- |
| -------- | -------- | -------- |
| DistributedDataObject| on(type: 'change', callback: Callback<{sessionId:string,fields:Array<string>}>): void | Subscribes to data changes.|
| DistributedDataObject| on(type: 'change', callback: Callback<{sessionId:string,fields:Array<string>}>): void | Subscribes to data changes.|
| DistributedDataObject| off(type: 'change', callback?: Callback<{sessionId:string,fields:Array<string>}>): void | Unsubscribes from data changes.**Callback**: specifies callback used to return changes of the distributed data object. If this parameter is not specified, all callbacks related to data changes will be unregistered.|
| DistributedDataObject| off(type: 'change', callback?: Callback<{sessionId:string,fields:Array<string>}>): void | Unsubscribes from data changes.<br>**Callback**: specifies callback used to return changes of the distributed data object. If this parameter is not specified, all callbacks related to data changes will be unregistered.|
### Observing Online or Offline Status
### Observing Online or Offline Status
Call **on()** to subscribe to status changes of a distributed data object. The status can be online or offline. When the status changes, a callback will be invoked to return the status. You can use **off()** to unsubscribe from the status changes.
Call **on()** to subscribe to status changes of a distributed data object. The status can be online or offline. When the status changes, a callback will be invoked to return the status. You can use **off()** to unsubscribe from the status changes.
**Table 5** APIs for observing status changes of a distributed data object
**Table 5** APIs for observing status changes of a distributed data object
| Class| API| Description|
| Class | API | Description |
| -------- | -------- | -------- |
| -------- | -------- | -------- |
| DistributedDataObject| on(type: 'status', callback: Callback<{sessionId:string,networkId:string,status:'online'\|'offline'}>): void | Subscribes to the status changes of a distributed data object.|
| DistributedDataObject| on(type: 'status', callback: Callback<{sessionId:string,networkId:string,status:'online'\|'offline'}>): void | Subscribes to the status changes of a distributed data object.|
| DistributedDataObject| off(type: 'status', callback?: Callback<{sessionId:string,deviceId:string,status:'online'\|'offline'}>): void | Unsubscribes from status changes of a distributed data object.|
| DistributedDataObject| off(type: 'status', callback?: Callback<{sessionId:string,deviceId:string,status:'online'\|'offline'}>): void | Unsubscribes from status changes of a distributed data object.|
...
@@ -69,19 +71,20 @@ The saved data will be released in the following cases:
...
@@ -69,19 +71,20 @@ The saved data will be released in the following cases:
- The application has been uninstalled.
- The application has been uninstalled.
- Data is successfully restored.
- Data is successfully restored.
**Table 6** APIs for saving a distributed data object and revoking the saving operation
**Table 6** APIs for saving a distributed data object and revoking the saving
| Class| API| Description|
| Class | API | Description |
| -------- | -------- | -------- |
| -------- | -------- | -------- |
| DistributedDataObject | save(deviceId: string): Promise<SaveSuccessResponse> | Saves a distributed data object. This API uses a promise to return the result.|
| DistributedDataObject | save(deviceId: string): Promise<SaveSuccessResponse> | Saves a distributed data object. This API uses a promise to return the result.|
| DistributedDataObject| save(deviceId: string, callback: AsyncCallback<SaveSuccessResponse>): void | Saves a distributed data object. This API uses an asynchronous callback to return the result.|
| DistributedDataObject | save(deviceId: string, callback: AsyncCallback<SaveSuccessResponse>): void | Saves a distributed data object. This API uses an asynchronous callback to return the result. |
| DistributedDataObject | revokeSave(callback: AsyncCallback<RevokeSaveSuccessResponse>): void | Revokes the data saving operation. This API uses an asynchronous callback to return the result.|
| DistributedDataObject | revokeSave(callback: AsyncCallback<RevokeSaveSuccessResponse>): void | Revokes the data saving operation. This API uses an asynchronous callback to return the result.|
| DistributedDataObject| revokeSave(): Promise<RevokeSaveSuccessResponse> | Revokes the data saving operation. This API uses a promise to return the result.|
| DistributedDataObject | revokeSave(): Promise<RevokeSaveSuccessResponse> | Revokes the data saving operation. This API uses a promise to return the result. |
## How to Develop
## How to Develop
The following example shows how to implement a distributed data object synchronization.
The following example shows how to implement distributed data object synchronization.
1. Import the @ohos.data.distributedDataObject module to the development environment.
1. Import the @ohos.data.distributedDataObject module to the development environment.
@@ -208,6 +212,7 @@ The following example shows how to implement a distributed data object synchroni
...
@@ -208,6 +212,7 @@ The following example shows how to implement a distributed data object synchroni
You can specify the callback to unregister. If you do not specify the callback, all data change callbacks of the distributed data object will be unregistered.
You can specify the callback to unregister. If you do not specify the callback, all data change callbacks of the distributed data object will be unregistered.
The sample code is as follows:
The sample code is as follows:
```js
```js
// Unregister the specified data change callback.
// Unregister the specified data change callback.
local_object.off("change",changeCallback);
local_object.off("change",changeCallback);
...
@@ -216,7 +221,9 @@ The following example shows how to implement a distributed data object synchroni
...
@@ -216,7 +221,9 @@ The following example shows how to implement a distributed data object synchroni
```
```
9. Subscribe to the status (online/offline) changes of the distributed data object. A callback will be invoked to report the status change when the target distributed data object goes online or offline.
9. Subscribe to the status (online/offline) changes of the distributed data object. A callback will be invoked to report the status change when the target distributed data object goes online or offline.