MozillaWiki

WebAPI/DataStore: Difference between revisions

Page Discussion

WebAPI/DataStore (view source)

Revision as of 23:49, 1 October 2014

2,291 bytes added ,  1 October 2014
no edit summary
No edit summary
 
(28 intermediate revisions by 5 users not shown)
Line 10: Line 10:
Support read-only stores like facebook contacts.<br>
Support read-only stores like facebook contacts.<br>
Support read/write stores like built-in contacts.<br>
Support read/write stores like built-in contacts.<br>
Support keeping a application-local cache of a data store. I.e. enable getting notified about changes to a data store so that the local cache can be kept up-to-date.<br>
Support keeping an application-local cache of a data store. I.e. enable getting notified about changes to a data store so that the local cache can be kept up-to-date.<br>
Enforce types of attributes (avoid to break other applications). 


== Why not...? ==
== Why not...? ==
Line 64: Line 63:
== Interface ==
== Interface ==


   interface DataStore {
  typedef (DOMString or unsigned long) DataStoreKey;
 
   interface DataStore : EventTarget {
     // Returns the label of the DataSource.
     // Returns the label of the DataSource.
     readonly attribute DOMString name;
     readonly attribute DOMString name;
 
     // Returns the origin of the DataSource (e.g., 'facebook.com').
     // Returns the origin of the DataSource (e.g., 'facebook.com').
     // TODO: defines what the value should be if owned by 'system'.
     // This value is the manifest URL of the owner app.
     readonly attribute DOMString owner;
     readonly attribute DOMString owner;
   
     // is readOnly a F(current_app, datastore) function? yes
     // is readOnly a F(current_app, datastore) function? yes
     readonly attribute boolean readOnly;
     readonly attribute boolean readOnly;
     // TODO: id should be incremental.
 
     Future<Object>  get(int id);
     // Promise<any>
     Future<void>   update(int id, Object obj);
     Promise get(DataStoreKey... id);
     Future<int>    add(Object obj);
     
     Future<boolean> remove(int id);
     // Promise<void>
     Future<void>   clear();
    Promise put(any obj, DataStoreKey id, optional DOMString revisionId = "");
 
     // Promise<DataStoreKey>
     Promise add(any obj, optional DataStoreKey id, optional DOMString revisionId = "");
 
     // Promise<boolean>
    Promise remove(DataStoreKey id, optional DOMString revisionId = "");
 
     // Promise<void>
    Promise clear(optional DOMString revisionId = "");
 
     readonly attribute DOMString revisionId;
     readonly attribute DOMString revisionId;
   
     attribute EventHandler onchange;
     attribute EventHandler onchange;
     Future<DataStoreChanges> getChanges(DOMString revisionId);
      
     // TODO: getAll(), getLength().
    // Promise<unsigned long>
    Promise getLength();
   
    DataStoreCursor sync(optional DOMString revisionId = "");
  };
 
  interface DataStoreCursor {
 
     // the DataStore
    readonly attribute DataStore store;
 
    // Promise<DataStoreTask>
    Promise next();
 
    void close();
   };
   };
    
    
   interface DataStoreChanges {
  enum DataStoreOperation {
    "add",
    "update",
    "remove",
    "clear",
    "done"
  };
 
  dictionary DataStoreTask {
    DOMString revisionId; 
 
    DataStoreOperation operation;
    DataStoreKey id;
    any data;
  };
 
  dictionary DataStoreChangeEventInit : EventInit {
    DOMString revisionId = "";
    DataStoreKey id = 0;
    DOMString operation = "";
    DOMStirng owner = "";
  };
 
  [Constructor(DOMString type, optional DataStoreChangeEventInit eventInitDict)]
   interface DataStoreChangeEvent : Event {
     readonly attribute DOMString revisionId;
     readonly attribute DOMString revisionId;
     readonly attribute int[] addedIds;
     readonly attribute DataStoreKey id;
     readonly attribute int[] updatedIds;
     readonly attribute DOMString operation;
     readonly attribute int[] removedIds;
     readonly attribute DOMString owner;
  }
 
  partial interface Navigator {
    Future<DataStore[]> getDataStores(DOMString name);
   };
   };


Line 102: Line 150:
     datastores-owned: {
     datastores-owned: {
       "contacts": {
       "contacts": {
         "readonly": true,
         "access": "readonly",
         "name": "Facebook contacts",
         "description": ...
       }
       }
     },
     },
Line 114: Line 162:
     datastores-access: {
     datastores-access: {
       "contacts": {
       "contacts": {
         "access": "readonly",
         "readonly": true,
         "description": ...
         "description": "Facebook contacts",
       }
       }
     },
     },
Line 121: Line 169:
   }
   }


== Incremental Schema ==
== Revisions and changes ==
DataStore is designed for sharing data among applications.  Applications will make some assumptions on data types of attributes.  If the data type of an attributes is not consistent among applications, applications may be broken.  So, data types of attributes should be enforced.
to define types of an attributes while attributes with a new path were found first time.  In another word, once a new object was added to a data store, its tree of attributes will be traveled, and define the type of new found attributes with the type of their values.


For example, if the following object is the object been added to a data store.
The revisionId is a UUID and it can be used to retrieve the delta between a particular revisionId and the current one using |sync()|


  {
== Examples ==
    SN: 123,
 
    name: "John Lin",
=== Basic operations ===
    info: {
      address: ".....",
      birth: Date(....),
    }
  }


Then, the types table of the data store is
  // Here we retrieve the list of DataStores called 'contacts'.
  SN: Integer
  navigator.getDataStores("contacts").then(function(stores) {
  name: String
    dump("DataStores called 'contacts': " + stores.length + "\n");
  info: object
   
  info address: String
    if (!stores.length) return;
  info birth: Date
   
    dump("Current revisionID: " + stores[0].revisionId + "\n");
   
    // Retrieve an object from the first DataStore.
    stores[0].get(42).then(function(obj) {
      // ...
     
      // Update an object
      obj.nick = 'baku';
      stores[0].put(obj, 42).then(function(id) {
        // id == 42
        // ...
      }, function(error) {
        // something wrong happened. Error is a DOMError object.
      });
    });
   
    // Delete an object
    stores[0].remove(23).then(function(success) {
      if (success) {
        // The object has been deleted.
      } else {
        // Object 23 didn't exist.
      }
    });
   
    // Storing a new object
    stores[0].add({ "nick": "baku", "email" : "a@b.c" }).then(function(id) {
      // ...
    });
  });


Then, the following object is added.
=== Sync ===
  {
    SN: 123,
    name: "John Lin",
    info: {
      address: ".....",
      birth: Date(....),
      phone: "123456",
    }
  }


The types table should be
The synchronization of  a DataStore with a 'private' app storage can be done using the 'sync' method. Calling this method, DataStore creates a DataStoreCursor that helps the app with the synchronization starting from scratch or for a valid revisionId. The sync operation can be terminated calling cursor.close(). If something changes in the DataStore when the cursor is synchronize the app, all the changes will be managed by the cursor as additional operation: this means that when the cursor completes its tasks, the app will be always in sync with the current revisionId of the DataStore.
  SN: Integer
  name: String
  info: object
  info address: String
  info birth: Date
  info phone: String


Every time a new object was added to a data store, the types of attributes would be checked against the types table of the data store. The action of adding will be failed if the type of any attribute does not match the type defined in the types table.
The basic usage of the cursor is this:
 
  navigator.getDataStores('contacts').then(functions(stores) {
    if (!stores.length) return;
 
    let cursor = stores[0].sync(/* a revisionId can be used here. If it's invalid it'll be ignored */);
 
    function cursorResolve(task) {
      // task.operation describes what the app has to do in order to be in sync with the current revision of this datastore.
      switch (task.operation) {
        case 'done':
          // No additional operation has to be done.
          dump("The current revision ID is: " + task.revisionId + "\n");
          return;
 
        case 'clear':
          // All the data you have are out-of-sync. Delete all of them.
          break;
 
        case 'add':
          // A new object has to be inserted
          dump("Adding id: " + task.id + " data: " + task.data + "\n");
          break;
 
        case 'update':
          // Something has to be updated
          dump("Updating id: " + task.id + " data: " + task.data + "\n");
          break;
 
        case 'remove':
          dump("Record: " + task.id + " must be removed\n");
          break;
      }
 
      cursor.next().then(cursorResolve);
    }
 
    // Cursor.next() always returns a promise.
    cursor.next().then(cursorResolve);
  });


== Issues ==
== Issues ==
  * {name, owner, value} is a complicated key.
  * {name, owner, value} is a complicated key.
  * UI: what to do when we have multiple access requests?
  * UI: what to do when we have multiple access requests?
* What's happening if the central gets changes during the process of local updates?
* |addedIds|, |removedIds| and |updatedIds| arrays should be synchronized. For example, the ID of record that has been updated and removed should only show up in the |removedIds| array. Need to define the behaviours.
  * Should all data stores with the same name share a schema?
  * Should all data stores with the same name share a schema?
  * Enforcing types can be a footgun. What should a data provider do if it decides some key should have a different type?
  * Enforcing types can be a footgun. What should a data provider do if it decides some key should have a different type?
[[Category:Web APIs]]
Chaasof
Confirmed users
1,340

edits

Retrieved from "https://wiki.allizom.org/Special:MobileDiff/660850...1021372"