rename setViews to setHandles and update particles (PolymerLabs#1390)

and replace all remaining 'views' with 'stores' and 'handles' appropriately, including documentation

extension/README.md

@@ -11,7 +11,7 @@ instance.
 The extension reads out schema.org-compatible data from web pages that are
 open when you activate the extension (by opening a new tab, activating the
 browser action, or manually).  When you accept suggestions that contain those
-views, they are synchronized to a **public** firebase.
+stores, they are synchronized to a **public** firebase.
 
 Eventually, the sync will be to your private data store (perhaps firebase,
 but other options will be available).
@@ -82,16 +82,16 @@ enabling the extension.
 ## Notes and Limitations
 
 The extension automatically tags [Product] with #shortlist, and all other
-views with #browserContext.
+stores with #browserContext.
 
 ## TODOs
 
 Nothing is ever complete.
 
-- [ ] Tags are how we differentiate between views. Once firebase supports it,
-  put additional tags on all views created by the extension (as many as
+- [ ] Tags are how we differentiate between stores. Once firebase supports it,
+  put additional tags on all stores created by the extension (as many as
   possible - the more information in tags, the better matches we'll be able to
   find).
 - [ ] De-duplicate data - some pages embed entities multiple times, and
-  reloads can cause the same information to be in the view many times. Keep
+  reloads can cause the same information to be in the store many times. Keep
   track of what we've sent and only send new entities.

runtime/dom-particle.js

@@ -10,7 +10,7 @@
 'use strict';
 
 import {assert} from '../platform/assert-web.js';
-import {Particle, ViewChanges} from './particle.js';
+import {Particle, HandleChanges} from './particle.js';
 import XenStateMixin from '../shell/components/xen/xen-state.js';
 
 /** @class DomParticle
@@ -98,11 +98,18 @@ export class DomParticle extends XenStateMixin(Particle) {
   _info() {
     return `---------- DomParticle::[${this.spec.name}]`;
   }
-  async setViews(handles) {
+  get _views() {
+    console.warn(`Particle ${this.spec.name} uses deprecated _views getter.`);
+    return this.handles;
+  }
+  async setViews(views) {
+    console.warn(`Particle ${this.spec.name} uses deprecated setViews method.`);
+    return this.setHandles(views);
+  }
+  async setHandles(handles) {
     this.handles = handles;
-    this._views = handles;
     let config = this.config;
-    this.when([new ViewChanges(handles, config.handles, 'change')], async () => {
+    this.when([new HandleChanges(handles, config.handles, 'change')], async () => {
       await this._handlesToProps(handles, config);
     });
     // make sure we invalidate once, even if there are no incoming handles

runtime/inner-PEC.js

@@ -209,15 +209,15 @@ export class InnerPEC {
       handleMap.set(name, handle);
 
       // Defer registration of handles with proxies until after particles have a chance to
-      // configure them in setViews.
+      // configure them in setHandles.
       registerList.push({proxy, particle, handle});
     });
 
     return [particle, async () => {
       resolve();
       let idx = this._pendingLoads.indexOf(p);
       this._pendingLoads.splice(idx, 1);
-      await particle.setViews(handleMap);
+      await particle.setHandles(handleMap);
       registerList.forEach(({proxy, particle, handle}) => proxy.register(particle, handle));
     }];
   }

runtime/multiplexer-dom-particle.js

@@ -24,13 +24,13 @@ export class MultiplexerDomParticle extends TransformationDomParticle {
       listHandleName,
       particleHandleName,
       hostedParticle,
-      views,
+      handles,
       arc) {
     let otherMappedHandles = [];
     let otherConnections = [];
     let index = 2;
     const skipConnectionNames = [listHandleName, particleHandleName];
-    for (let [connectionName, otherHandle] of views) {
+    for (let [connectionName, otherHandle] of handles) {
       if (skipConnectionNames.includes(connectionName)) {
         continue;
       }
@@ -52,12 +52,12 @@ export class MultiplexerDomParticle extends TransformationDomParticle {
     return [otherMappedHandles, otherConnections];
   }
 
-  async setViews(views) {
+  async setHandles(handles) {
     this.handleIds = {};
     let arc = await this.constructInnerArc();
     const listHandleName = 'list';
     const particleHandleName = 'hostedParticle';
-    let particleHandle = views.get(particleHandleName);
+    let particleHandle = handles.get(particleHandleName);
     let hostedParticle = null;
     let otherMappedHandles = [];
     let otherConnections = [];
@@ -66,18 +66,18 @@ export class MultiplexerDomParticle extends TransformationDomParticle {
       if (hostedParticle) {
         [otherMappedHandles, otherConnections] =
             await this._mapParticleConnections(
-                listHandleName, particleHandleName, hostedParticle, views, arc);
+                listHandleName, particleHandleName, hostedParticle, handles, arc);
       }
     }
     this.setState({
       arc,
-      type: views.get(listHandleName).type,
+      type: handles.get(listHandleName).type,
       hostedParticle,
       otherMappedHandles,
       otherConnections
     });
 
-    super.setViews(views);
+    super.setHandles(handles);
   }
 
   async willReceiveProps(
@@ -119,7 +119,7 @@ export class MultiplexerDomParticle extends TransformationDomParticle {
                 listHandleName,
                 particleHandleName,
                 resolvedHostedParticle,
-                this._views,
+                this.handles,
                 arc);
       }
       let hostedSlotName = [...resolvedHostedParticle.slots.keys()][0];
@@ -140,7 +140,7 @@ export class MultiplexerDomParticle extends TransformationDomParticle {
                 item,
                 itemHandle,
                 {name: hostedSlotName, id: slotId},
-                {connections: otherConnections, views: otherMappedHandles}),
+                {connections: otherConnections, handles: otherMappedHandles}),
             this);
         itemHandle.set(item);
       } catch (e) {

runtime/particle.js

@@ -32,20 +32,26 @@ export class Particle {
     this.capabilities = capabilities || {};
   }
 
-  /** @method setViews(views)
-   * This method is invoked with a handle for each view this particle
-   * is registered to interact with, once those views are ready for
+  /** @method setHandles(handles)
+   * This method is invoked with a handle for each store this particle
+   * is registered to interact with, once those handles are ready for
    * interaction. Override the method to register for events from
-   * the views.
+   * the handles.
    *
-   * Views is a map from view names to view handles.
+   * Handles is a map from handle names to store handles.
+   */
+  setHandles(handles) {
+  }
+
+  /** @method setViews(views)
+   * This method is deprecated. Use setHandles instead.
    */
   setViews(views) {
   }
 
   /** @method onHandleSync(handle, model, version)
    * Called for handles that are configured with both keepSynced and notifySync, when they are
-   * updated with the full model of their data. This will occur once after setViews() and any time
+   * updated with the full model of their data. This will occur once after setHandles() and any time
    * thereafter if the handle is resynchronized.
    *
    * handle: The Handle instance that was updated.
@@ -159,19 +165,19 @@ export class Particle {
     this.stateHandlers.get(state).forEach(f => f(value));
   }
 
-  /** @method on(views, names, kind, f)
-   * Convenience method for registering a callback on multiple views at once.
+  /** @method on(handles, names, kind, f)
+   * Convenience method for registering a callback on multiple handles at once.
    *
-   * views is a map from names to view handles
-   * names indicates the views which should have a callback installed on them
+   * handles is a map from names to store handles
+   * names indicates the handles which should have a callback installed on them
    * kind is the kind of event that should be registered for
    * f is the callback function
    */
-  on(views, names, kind, f) {
+  on(handles, names, kind, f) {
     if (typeof names == 'string')
       names = [names];
-    let trace = Tracing.start({cat: 'particle', names: this.constructor.name + '::on', args: {view: names, event: kind}});
-    names.forEach(name => views.get(name).on(kind, Tracing.wrap({cat: 'particle', name: this.constructor.name, args: {view: name, event: kind}}, f), this));
+    let trace = Tracing.start({cat: 'particle', names: this.constructor.name + '::on', args: {handle: names, event: kind}});
+    names.forEach(name => handles.get(name).on(kind, Tracing.wrap({cat: 'particle', name: this.constructor.name, args: {handle: name, event: kind}}, f), this));
     trace.end();
   }
 
@@ -209,7 +215,7 @@ export class Particle {
     return this.setDescriptionPattern('_pattern_', pattern);
   }
   setDescriptionPattern(connectionName, pattern) {
-    let descriptions = this._views.get('descriptions');
+    let descriptions = this.handles.get('descriptions');
     if (descriptions) {
       descriptions.store(new descriptions.entityClass({key: connectionName, value: pattern}, connectionName));
       return true;
@@ -218,21 +224,21 @@ export class Particle {
   }
 }
 
-export class ViewChanges {
-  constructor(views, names, type) {
+export class HandleChanges {
+  constructor(handles, names, type) {
     if (typeof names == 'string')
       names = [names];
     this.names = names;
-    this.views = views;
+    this.handles = handles;
     this.type = type;
   }
   register(particle, f) {
     let modelCount = 0;
     let afterAllModels = () => { if (++modelCount == this.names.length) { f(); } };
 
     for (let name of this.names) {
-      let view = this.views.get(name);
-      view.synchronize(this.type, afterAllModels, f, particle);
+      let handle = this.handles.get(name);
+      handle.synchronize(this.type, afterAllModels, f, particle);
     }
   }
 }

runtime/scheduler.js

@@ -34,7 +34,7 @@ export class Scheduler {
   }
 
   enqueue(handle, eventRecords) {
-    let trace = Tracing.flow({cat: 'handle', name: 'ViewBase::_fire flow'}).start();
+    let trace = Tracing.flow({cat: 'handle', name: 'StorageBase::_fire flow'}).start();
     if (this.frameQueue.length == 0 && eventRecords.length > 0)
       this._asyncProcess();
     if (!this._idleResolver) {

runtime/test/arc-tests.js

@@ -102,12 +102,12 @@ describe('Arc', function() {
       import 'runtime/test/artifacts/test-particles.manifest'
       
       recipe
-        slot 'slotid' as s0
-        use as v0
+        slot 'slotid' as slot0
+        use as handle0
         Multiplexer
           hostedParticle = ConsumerParticle
-          consume annotation as s0
-          list <- v0
+          consume annotation as slot0
+          list <- handle0
 
     `, {loader, fileName: './manifest.manifest'});
 

runtime/test/artifacts/hello.js

@@ -10,8 +10,8 @@
 
 defineParticle(({Particle}) => {
   return class Hello extends Particle {
-    setViews(views) {
-      let text = views.get('text');
+    setHandles(handles) {
+      let text = handles.get('text');
       let entity = new (text.entityClass)({});
       entity.value = 'Hello, world!';
       text.set(entity);

runtime/test/artifacts/outer-particle.js

@@ -11,23 +11,23 @@
 
 defineParticle(({Particle}) => {
   return class P extends Particle {
-    async setViews(views) {
+    async setHandles(handles) {
       let arc = await this.constructInnerArc();
-      let inputHandle = views.get('input');
-      let outputHandle = views.get('output');
+      let inputHandle = handles.get('input');
+      let outputHandle = handles.get('output');
       let inHandle = await arc.createHandle(inputHandle.type, 'input');
       let outHandle = await arc.createHandle(outputHandle.type, 'output');
-      let particle = await views.get('particle').get();
+      let particle = await handles.get('particle').get();
 
       let recipe = Particle.buildManifest`
         ${particle}
 
         recipe
-          use ${inHandle} as v1
-          use ${outHandle} as v2
+          use ${inHandle} as handle1
+          use ${outHandle} as handle2
           ${particle.name}
-            foo <- v1
-            bar -> v2
+            foo <- handle1
+            bar -> handle2
       `;
 
       try {

runtime/test/artifacts/test-particle.js

@@ -10,10 +10,10 @@
 
 defineParticle(({Particle}) => {
   return class Hello extends Particle {
-    setViews(views) {
-      const Bar = views.get('bar').entityClass;
-      views.get('foo').get().then(result => {
-        let bar = views.get('bar');
+    setHandles(handles) {
+      const Bar = handles.get('bar').entityClass;
+      handles.get('foo').get().then(result => {
+        let bar = handles.get('bar');
         bar.set(new bar.entityClass({value: result.value + 1}));
       });
       // TODO: what is this meant to do?

runtime/test/artifacts/transformations/test-multiplex-slots-particle.js

@@ -19,13 +19,13 @@ defineParticle(({TransformationDomParticle}) => {
       }
     }
 
-    async setViews(views) {
+    async setHandles(handles) {
       let arc = await this.constructInnerArc();
-      let hostedParticle = await views.get('particle').get();
+      let hostedParticle = await handles.get('particle').get();
 
-      this.setState({arc, hostedParticle, type: views.get('foos').type});
+      this.setState({arc, hostedParticle, type: handles.get('foos').type});
 
-      super.setViews(views);
+      super.setHandles(handles);
     }
 
     async willReceiveProps({foos}) {
@@ -51,11 +51,11 @@ defineParticle(({TransformationDomParticle}) => {
             consume ${hostedSlotName}
 
           recipe
-            use '${fooHandle._id}' as v1
-            slot '${slotId}' as s1
+            use '${fooHandle._id}' as handle1
+            slot '${slotId}' as slot1
             ${hostedParticle.name}
-              foo <- v1
-              consume ${hostedSlotName} as s1
+              foo <- handle1
+              consume ${hostedSlotName} as slot1
         `;
 
         try {

runtime/test/manifest-parser-test.js

@@ -23,7 +23,7 @@ describe('manifest parser', function() {
     parse(`
       recipe Recipe`);
   });
-  it('parses recipes that map views', () => {
+  it('parses recipes that map handles', () => {
     parse(`
       recipe Thing
         map #someTag
@@ -34,7 +34,7 @@ describe('manifest parser', function() {
       recipe Recipe
         SomeParticle`);
   });
-  it('parses recipes that connect particles to views', () => {
+  it('parses recipes that connect particles to handles', () => {
     parse(`
       recipe Recipe
         SomeParticle
@@ -46,7 +46,7 @@ describe('manifest parser', function() {
     parse(`
       particle SomeParticle`);
   });
-  it('parses recipes that name views and particles', () => {
+  it('parses recipes that name handles and particles', () => {
     parse(`
       recipe Recipe
         SomeParticle as thing
@@ -74,7 +74,7 @@ describe('manifest parser', function() {
         a.a = b.b
         X.a #tag <- a.y`);
   });
-  it('parses manifests with views', () => {
+  it('parses manifests with stores', () => {
     parse(`
       schema Person
         Text lastName