MozillaWiki

WebAPI/DataStore: Difference between revisions

Page Discussion

WebAPI/DataStore (view source)

Revision as of 23:49, 1 October 2014

2,155 bytes added ,  1 October 2014
no edit summary
No edit summary
No edit summary
 
(22 intermediate revisions by 3 users not shown)
Line 63: Line 63:
== Interface ==
== Interface ==


  typedef (DOMString or unsigned long) DataStoreKey;
 
   interface DataStore : EventTarget {
   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').
     // This value is the manifest URL of the owner app.
     // This value is the manifest URL of the owner app.
Line 73: Line 75:
     // 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;
   
 
     Promise<Object> get(int id);
     // Promise<any>
     Promise<void>   update(int id, Object obj);
    Promise get(DataStoreKey... id);
     Promise<int>    add(Object obj);
     
     Promise<boolean> remove(int id);
     // Promise<void>
     Promise<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;
    Promise<DataStoreChanges> getChanges(DOMString revisionId);
      
      
     // TODO: getAll(), getLength().
     // Promise<unsigned long>
    Promise getLength();
   
    DataStoreCursor sync(optional DOMString revisionId = "");
   };
   };
    
    
   interface DataStoreChanges {
   interface DataStoreCursor {
 
    // the DataStore
    readonly attribute DataStore store;
 
    // Promise<DataStoreTask>
    Promise next();
 
    void close();
  };
 
  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 {
    Promise<sequence<DataStore>> getDataStores(DOMString name);
   };
   };


Line 106: Line 150:
     datastores-owned: {
     datastores-owned: {
       "contacts": {
       "contacts": {
         "readonly": true,
         "access": "readonly",
         "description": "Facebook contacts",
         "description": ...
       }
       }
     },
     },
Line 118: Line 162:
     datastores-access: {
     datastores-access: {
       "contacts": {
       "contacts": {
         "access": "readonly",
         "readonly": true,
         "description": ...
         "description": "Facebook contacts",
       }
       }
     },
     },
Line 127: Line 171:
== Revisions and changes ==
== Revisions and changes ==


The revisionId is a UUID and it can be used to retrieve the delta between a particular revisionId and the current one. This operation is done using |Promise<DataStoreChanges> getChanges(DOMString revisionId);|. Note that the object DataStoreChanges contains only useful operations: for example, the ID of record that has been updated and removed only shows up in the |removedIds| array.
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 ==
== Examples ==
Line 147: Line 191:
       // Update an object
       // Update an object
       obj.nick = 'baku';
       obj.nick = 'baku';
       stores[0].update(42, obj).then(function(id) {
       stores[0].put(obj, 42).then(function(id) {
         // id == 42
         // id == 42
         // ...
         // ...
Line 163: Line 207:
       }
       }
     });
     });
 
   
     // Storing a new object
     // Storing a new object
     stores[0].add({ "nick": "baku", "email" : "a@b.c" }).then(function(id) {
     stores[0].add({ "nick": "baku", "email" : "a@b.c" }).then(function(id) {
Line 170: Line 214:
   });
   });


=== Revisions ===
=== Sync ===
 
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.
 
The basic usage of the cursor is this:


   // Let's assume that I have a revisionId stored somewhere (IndexedDb? LocalStorage?)
   navigator.getDataStores('contacts').then(functions(stores) {
   var revisionId = 'b66e9248-5990-4ac3-9f5d-3cdeb02b337f';
    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);
    }
    
    
  navigator.getDataStores('contacts').then(function(stores) {
    // Cursor.next() always returns a promise.
     if (!stores.length) return;
     cursor.next().then(cursorResolve);
   
    stores[0].getChanges(revisionId).then(function(delta) {
      // TODO
    });
   });
   });


Line 186: Line 262:
  * {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?
  * 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/698592...1021372"