Application Manifest

For the application that provides the data store, its manifest MUST be claimed to own the data store by datastores-owned, where the JSON object can contain multiple properties representing different names of data stores respectively. Each data store can use readonly to specify whether the data store can be read by other applications and description to describe the purpose.

As shown as the following example, if a Facebook applicaton wants to provide a read-only fb-contacts data store, its manifest MUST be claimed to own the data store by setting the attribute readonly to true.

          {
            datastores-owned: {
              "fb-contacts": {
                "readonly": true,
                "description": "own the Facebook contacts data store"
              }
            }
          }
        

For the application that wants to access the data store, its manifest MUST be claimed to access the data store by datastores-access, where the JSON object can contain multiple properties representing different names of data stores respectively. Each data store can use access to specify the application's accessibility and description to describe the purpose.

As shown as the following example, if the application wants to read or modify (e.g., add, update, remove, clear... etc) the content of the fb-contacts data store, its manifest MUST be claimed to access the fb-contacts data store by setting the attribute access to readwrite.

          {
            datastores-access: {
              "fb-contacts": {
                "access": "readwrite",
                "description": "access (read and write) the Facebook contacts data stores"
              }
            }
          }
        

As shown as the following example, if the application simply wants to read the content of the fb-contacts data store without the need of modifying it, its manifest MUST be claimed to access the fb-contacts data store by setting the attribute access to readonly.

          {
            datastores-access: {
              "fb-contacts": {
                "access": "readonly",
                "description": "access (read only) the Facebook contacts data store"
              }
            }
          }
        

Permission Model

The Data Store API can be exposed to trusted or untrusted contents.

Steps

The getDataStores method when invoked MUST run the following steps:

1. Let promise be a new Promise object and resolver be its associated resolver.
2. Return promise to the caller.
3. Make a request to the system to retrieve the data store(s) with the name equal to the name parameter passed in the request, where the caller application has claimed the data store access by datastores-access in its manifest.
4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
5. When the request has been successfully completed:
1. Let dataStores be the array of the retrieved DataStore elements.
2. Invoke resolver's fulfill algorithm with dataStores as the value argument.

Steps

The get method when invoked MUST run the following steps:

1. Let promise be a new Promise object and resolver be its associated resolver.
2. Return promise to the caller.
3. Make a request to the data store to retrieve the data record(s) with the identifier equal to the id parameter passed in the request.
4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
5. When the request has been successfully completed:
1. Let dataRecord be the retrieved data record(s).
2. Invoke resolver's fulfill algorithm with dataRecord as the value argument.

The update method when invoked MUST run the following steps:

1. Let promise be a new Promise object and resolver be its associated resolver.
2. Return promise to the caller.
3. If the readOnly attribute of the current data store is true to the caller, invoke resolver's reject algorithm without assigning a value to the value argument.
4. Make a request to the data store to retrieve the data record with the identifier equal to the id parameter passed in the request.
5. If an error occurs invoke resolver's reject algorithm with error as the value argument.
6. When the request has been successfully completed:
1. Let dataRecord be the retrieved data record.
2. Replace dataRecord by the data parameter passed in the request.
3. Make a request to the data store to save dataRecord back to the data store.
4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
5. When the request has been successfully completed:
1. Invoke resolver's fulfill algorithm without assigning a value to the value argument.

The insert method when invoked MUST run the following steps:

1. Let promise be a new Promise object and resolver be its associated resolver.
2. Return promise to the caller.
3. If the readOnly attribute of the current data store is true to the caller, invoke resolver's reject algorithm without assigning a value to the value argument.
4. Make a request to the data store to add the data parameter passed in the request.
5. If an error occurs invoke resolver's reject algorithm with error as the value argument.
6. When the request has been successfully completed:
1. Let id be the generated identifier of the added data record.
2. Invoke resolver's fulfill algorithm with id as the value argument.

The remove method when invoked MUST run the following steps:

1. Let promise be a new Promise object and resolver be its associated resolver.
2. Return promise to the caller.
3. If the readOnly attribute of the current data store is true to the caller, invoke resolver's reject algorithm with false as the value argument.
4. Make a request to the data store to retrieve the data record(s) with the identifier equal to the id parameter passed in the request.
5. If an error occurs invoke resolver's reject algorithm with false as the value argument.
6. When the request has been successfully completed:
1. Make a request to the data store to delete the data record(s) with the identifier equal to the id parameter passed in the request.
2. If an error occurs invoke resolver's reject algorithm with false as the value argument.
3. When the request has been successfully completed:
1. Invoke resolver's fulfill algorithm with true as the value argument.

The clear method when invoked MUST run the following steps:

1. Let promise be a new Promise object and resolver be its associated resolver.
2. Return promise to the caller.
3. If the readOnly attribute of the current data store is true to the caller, invoke resolver's reject algorithm without assigning a value to the value argument.
4. Make a request to the data store to clear all the data records.
5. If an error occurs invoke resolver's reject algorithm with error as the value argument.
6. When the request has been successfully completed:
1. Invoke resolver's fulfill algorithm without assigning a value to the value argument.

The getLength method when invoked MUST run the following steps:

1. Let promise be a new Promise object and resolver be its associated resolver.
2. Return promise to the caller.
3. Make a request to the data store to get the total number of data records.
4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
5. When the request has been successfully completed:
1. Let length be the total number of data records saved in the data store.
2. Invoke resolver's fulfill algorithm with length as the value argument.

The sync method when invoked MUST run the following steps:

1. Make a request to the system to retrieve a cursor that can iterate through the change history of the current data store.
2. When the request has been successfully completed:
1. Let dataStoreCursor be a new instance of DataStoreCursor.
2. Set the store of dataStoreCursor to the current data store.
3. Return dataStoreCursor.

Event handlers

The following are the event handlers (and their corresponding event types) that MUST be supported as attributes by the DataStore object.

Steps

The next method when invoked MUST run the following steps:

1. Let promise be a new Promise object and resolver be its associated resolver.
2. Return promise to the caller.
3. Make a request to the system to retrieve the information of the next operation that changes a data record in the data store.
4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
5. When the request has been successfully completed:
1. Let dataStoreTask be a new instance of DataStoreTask:
1. Set the revisionId of dataStoreTask to the revision of the data store, which changes a data record.
2. Set the id of dataStoreTask to the identifier of the changed data record in the data store.
3. Set the operation of dataStoreTask to the type of operation that changes the data record in the data store.
4. Set the data of dataStoreTask to the changed data record in the data store.
2. Invoke resolver's fulfill algorithm with dataStoreTask as the value argument.

The close method when invoked MUST run the following steps:

1. Make a request to the system to terminate the current cursor iterating through the change history of the data store.