Mojo JS bindings: introduce concepts that are more similar to C++ bindings:

- InterfacePtrInfo
- InterfaceRequest
- InterfacePtr
- Binding

BUG=579646

Review-Url: https://codereview.chromium.org/2549683002
Cr-Commit-Position: refs/heads/master@{#436201}

mojo/edk/js/test/run_js_integration_tests.cc

@@ -45,14 +45,22 @@ void RunTest(std::string test) {
   gin::RunTestFromFile(path, &delegate, false);
 }
 
-TEST(JSTest, connection) {
+TEST(JSTest, Connection) {
   RunTest("connection_tests.js");
 }
 
-TEST(JSTest, sample_service) {
+TEST(JSTest, SampleService) {
   RunTest("sample_service_tests.js");
 }
 
+TEST(JSTest, InterfacePtr) {
+  RunTest("interface_ptr_tests.js");
+}
+
+TEST(JSTest, Binding) {
+  RunTest("binding_tests.js");
+}
+
 }  // namespace
 }  // namespace js
 }  // namespace edk

mojo/edk/js/tests/BUILD.gn

@@ -24,7 +24,9 @@ source_set("js_to_cpp_tests") {
   ]
 
   data = [
+    "binding_tests.js",
     "connection_tests.js",
+    "interface_ptr_tests.js",
     "js_to_cpp_tests.js",
     "sample_service_tests.js",
   ]

mojo/edk/js/tests/binding_tests.js

+// Copyright 2016 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+define([
+    "gin/test/expect",
+    "mojo/public/js/bindings",
+    "mojo/public/interfaces/bindings/tests/math_calculator.mojom",
+    "mojo/public/js/threading",
+    "gc",
+], function(expect,
+            bindings,
+            math,
+            threading,
+            gc) {
+  testIsBound()
+      .then(testReusable)
+      .then(function() {
+    this.result = "PASS";
+    gc.collectGarbage();  // should not crash
+    threading.quit();
+  }.bind(this)).catch(function(e) {
+    this.result = "FAIL: " + (e.stack || e);
+    threading.quit();
+  }.bind(this));
+
+  function CalculatorImpl() {
+    this.total = 0;
+  }
+
+  CalculatorImpl.prototype.clear = function() {
+    this.total = 0;
+    return Promise.resolve({value: this.total});
+  };
+
+  CalculatorImpl.prototype.add = function(value) {
+    this.total += value;
+    return Promise.resolve({value: this.total});
+  };
+
+  CalculatorImpl.prototype.multiply = function(value) {
+    this.total *= value;
+    return Promise.resolve({value: this.total});
+  };
+
+  function testIsBound() {
+    var binding = new bindings.Binding(math.Calculator, new CalculatorImpl());
+    expect(binding.isBound()).toBeFalsy();
+
+    var calc = new math.CalculatorPtr();
+    var request = bindings.makeRequest(calc);
+    binding.bind(request);
+    expect(binding.isBound()).toBeTruthy();
+
+    binding.close();
+    expect(binding.isBound()).toBeFalsy();
+
+    return Promise.resolve();
+  }
+
+  function testReusable() {
+    var calc1 = new math.CalculatorPtr();
+    var calc2 = new math.CalculatorPtr();
+
+    var calcBinding = new bindings.Binding(math.Calculator,
+                                           new CalculatorImpl(),
+                                           bindings.makeRequest(calc1));
+
+    var promise = calc1.add(2).then(function(response) {
+      expect(response.value).toBe(2);
+      calcBinding.bind(bindings.makeRequest(calc2));
+      return calc2.add(2);
+    }).then(function(response) {
+      expect(response.value).toBe(4);
+      return Promise.resolve();
+    });
+
+    return promise;
+  }
+});

mojo/edk/js/tests/interface_ptr_tests.js

+// Copyright 2016 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+define([
+    "gin/test/expect",
+    "mojo/public/js/bindings",
+    "mojo/public/interfaces/bindings/tests/math_calculator.mojom",
+    "mojo/public/js/threading",
+    "gc",
+], function(expect,
+            bindings,
+            math,
+            threading,
+            gc) {
+  testIsBound()
+      .then(testEndToEnd)
+      .then(testReusable)
+      .then(function() {
+    this.result = "PASS";
+    gc.collectGarbage();  // should not crash
+    threading.quit();
+  }.bind(this)).catch(function(e) {
+    this.result = "FAIL: " + (e.stack || e);
+    threading.quit();
+  }.bind(this));
+
+  function CalculatorImpl() {
+    this.total = 0;
+  }
+
+  CalculatorImpl.prototype.clear = function() {
+    this.total = 0;
+    return Promise.resolve({value: this.total});
+  };
+
+  CalculatorImpl.prototype.add = function(value) {
+    this.total += value;
+    return Promise.resolve({value: this.total});
+  };
+
+  CalculatorImpl.prototype.multiply = function(value) {
+    this.total *= value;
+    return Promise.resolve({value: this.total});
+  };
+
+  function testIsBound() {
+    var calc = new math.CalculatorPtr();
+    expect(calc.ptr.isBound()).toBeFalsy();
+
+    var request = bindings.makeRequest(calc);
+    expect(calc.ptr.isBound()).toBeTruthy();
+
+    calc.ptr.reset();
+    expect(calc.ptr.isBound()).toBeFalsy();
+
+    return Promise.resolve();
+  }
+
+  function testEndToEnd() {
+    var calc = new math.CalculatorPtr();
+    var calcBinding = new bindings.Binding(math.Calculator,
+                                           new CalculatorImpl(),
+                                           bindings.makeRequest(calc));
+
+    var promise = calc.add(2).then(function(response) {
+      expect(response.value).toBe(2);
+      return calc.multiply(5);
+    }).then(function(response) {
+      expect(response.value).toBe(10);
+      return calc.clear();
+    }).then(function(response) {
+      expect(response.value).toBe(0);
+      return Promise.resolve();
+    });
+
+    return promise;
+  }
+
+  function testReusable() {
+    var calc = new math.CalculatorPtr();
+    var calcImpl1 = new CalculatorImpl();
+    var calcBinding1 = new bindings.Binding(math.Calculator,
+                                            calcImpl1,
+                                            bindings.makeRequest(calc));
+    var calcImpl2 = new CalculatorImpl();
+    var calcBinding2 = new bindings.Binding(math.Calculator, calcImpl2);
+
+    var promise = calc.add(2).then(function(response) {
+      expect(response.value).toBe(2);
+      calcBinding2.bind(bindings.makeRequest(calc));
+      return calc.add(2);
+    }).then(function(response) {
+      expect(response.value).toBe(2);
+      expect(calcImpl1.total).toBe(2);
+      expect(calcImpl2.total).toBe(2);
+      return Promise.resolve();
+    });
+
+    return promise;
+  }
+});

mojo/edk/js/tests/sample_service_tests.js

@@ -7,11 +7,10 @@ define([
     "mojo/public/interfaces/bindings/tests/sample_service.mojom",
     "mojo/public/interfaces/bindings/tests/sample_import.mojom",
     "mojo/public/interfaces/bindings/tests/sample_import2.mojom",
-    "mojo/public/js/connection",
+    "mojo/public/js/bindings",
     "mojo/public/js/core",
     "mojo/public/js/threading",
-  ], function(expect, sample, imported, imported2, connection, core,
-              threading) {
+  ], function(expect, sample, imported, imported2, bindings, core, threading) {
   testDefaultValues()
       .then(testSampleService)
       .then(function() {
@@ -71,26 +70,23 @@ define([
     function ServiceImpl() {
     }
 
-    ServiceImpl.prototype = Object.create(sample.Service.stubClass.prototype);
-
     ServiceImpl.prototype.frobinate = function(foo, baz, port) {
       checkFoo(foo);
       expect(baz).toBe(sample.Service.BazOptions.EXTRA);
-      expect(core.isHandle(port)).toBeTruthy();
+      bindings.ProxyBindings(port).close();
       return Promise.resolve({result: 1234});
     };
 
     var foo = makeFoo();
     checkFoo(foo);
 
-    var sampleServicePipe = core.createMessagePipe();
-    var connection0 = new connection.Connection(sampleServicePipe.handle0,
-                                                ServiceImpl);
-    var connection1 = new connection.Connection(
-        sampleServicePipe.handle1, undefined, sample.Service.proxyClass);
+    var service = new sample.ServicePtr();
+    var request = bindings.makeRequest(service);
+    var serviceBinding = new bindings.Binding(
+        sample.Service, new ServiceImpl(), request);
 
     var pipe = core.createMessagePipe();
-    var promise = connection1.remote.frobinate(
+    var promise = service.frobinate(
         foo, sample.Service.BazOptions.EXTRA, pipe.handle0)
             .then(function(response) {
       expect(response.result).toBe(1234);

mojo/public/js/bindings.js

@@ -3,115 +3,140 @@
 // found in the LICENSE file.
 
 define("mojo/public/js/bindings", [
-  "mojo/public/js/router",
+  "mojo/public/js/connection",
   "mojo/public/js/core",
-], function(router, core) {
+], function(connection, core) {
 
-  var Router = router.Router;
+  // ---------------------------------------------------------------------------
 
-  var kProxyProperties = Symbol("proxyProperties");
-  var kStubProperties = Symbol("stubProperties");
-
-  // Public proxy class properties that are managed at runtime by the JS
-  // bindings. See ProxyBindings below.
-  function ProxyProperties(receiver) {
-    this.receiver = receiver;
+  function InterfacePtrInfo(handle, version) {
+    this.handle = handle;
+    this.version = version;
   }
 
-  // TODO(hansmuller): remove then after 'Client=' has been removed from Mojom.
-  ProxyProperties.prototype.getLocalDelegate = function() {
-    return this.local && StubBindings(this.local).delegate;
+  InterfacePtrInfo.prototype.isValid = function() {
+    return core.isHandle(this.handle);
   }
 
-  // TODO(hansmuller): remove then after 'Client=' has been removed from Mojom.
-  ProxyProperties.prototype.setLocalDelegate = function(impl) {
-    if (this.local)
-      StubBindings(this.local).delegate = impl;
-    else
-      throw new Error("no stub object");
-  }
+  // ---------------------------------------------------------------------------
 
-  ProxyProperties.prototype.close = function() {
-    this.connection.close();
+  function InterfaceRequest(handle) {
+    this.handle = handle;
   }
 
-  // Public stub class properties that are managed at runtime by the JS
-  // bindings. See StubBindings below.
-  function StubProperties(delegate) {
-    this.delegate = delegate;
+  InterfaceRequest.prototype.isValid = function() {
+    return core.isHandle(this.handle);
   }
 
-  StubProperties.prototype.close = function() {
-    this.connection.close();
+  // ---------------------------------------------------------------------------
+
+  function makeRequest(interfacePtr) {
+    var pipe = core.createMessagePipe();
+    interfacePtr.ptr.bind(new InterfacePtrInfo(pipe.handle0, 0));
+    return new InterfaceRequest(pipe.handle1);
   }
 
-  // The base class for generated proxy classes.
-  function ProxyBase(receiver) {
-    this[kProxyProperties] = new ProxyProperties(receiver);
+  // ---------------------------------------------------------------------------
 
-    // TODO(hansmuller): Temporary, for Chrome backwards compatibility.
-    if (receiver instanceof Router)
-      this.receiver_ = receiver;
+  // Operations used to setup/configure an interface pointer. Exposed as the
+  // |ptr| field of generated interface pointer classes.
+  function InterfacePtrController(interfaceType) {
+    this.version = 0;
+    this.connection = null;
+
+    this.interfaceType_ = interfaceType;
   }
 
-  // The base class for generated stub classes.
-  function StubBase(delegate) {
-    this[kStubProperties] = new StubProperties(delegate);
+  InterfacePtrController.prototype.bind = function(interfacePtrInfo) {
+    this.reset();
+    this.version = interfacePtrInfo.version;
+    this.connection = new connection.Connection(
+      interfacePtrInfo.handle, undefined, this.interfaceType_.proxyClass);
   }
 
-  // TODO(hansmuller): remove everything except the connection property doc
-  // after 'Client=' has been removed from Mojom.
+  InterfacePtrController.prototype.isBound = function() {
+    return this.connection !== null;
+  }
 
-  // Provides access to properties added to a proxy object without risking
-  // Mojo interface name collisions. Unless otherwise specified, the initial
-  // value of all properties is undefined.
-  //
-  // ProxyBindings(proxy).connection - The Connection object that links the
-  //   proxy for a remote Mojo service to an optional local stub for a local
-  //   service. The value of ProxyBindings(proxy).connection.remote == proxy.
-  //
-  // ProxyBindings(proxy).local  - The "local" stub object whose delegate
-  //   implements the proxy's Mojo client interface.
-  //
-  // ProxyBindings(proxy).setLocalDelegate(impl) - Sets the implementation
-  //   delegate of the proxy's client stub object. This is just shorthand
-  //   for |StubBindings(ProxyBindings(proxy).local).delegate = impl|.
-  //
-  // ProxyBindings(proxy).getLocalDelegate() - Returns the implementation
-  //   delegate of the proxy's client stub object. This is just shorthand
-  //   for |StubBindings(ProxyBindings(proxy).local).delegate|.
+  // Although users could just discard the object, reset() closes the pipe
+  // immediately.
+  InterfacePtrController.prototype.reset = function() {
+    if (!this.isBound())
+      return;
 
-  function ProxyBindings(proxy) {
-    return (proxy instanceof ProxyBase) ? proxy[kProxyProperties] : proxy;
+    this.version = 0;
+    this.connection.close();
+    this.connection = null;
   }
 
-  // TODO(hansmuller): remove the remote doc after 'Client=' has been
-  // removed from Mojom.
+  // TODO(yzshen): Implement the following methods.
+  //   InterfacePtrController.prototype.setConnectionErrorHandler
+  //   InterfacePtrController.prototype.passInterface
+  //   InterfacePtrController.prototype.queryVersion
+  //   InterfacePtrController.prototype.requireVersion
+
+  // ---------------------------------------------------------------------------
 
-  // Provides access to properties added to a stub object without risking
-  // Mojo interface name collisions. Unless otherwise specified, the initial
-  // value of all properties is undefined.
+  // |request| could be omitted and passed into bind() later.
+  // NOTE: |impl| shouldn't hold a reference to this object, because that
+  // results in circular references.
   //
-  // StubBindings(stub).delegate - The optional implementation delegate for
-  //  the Mojo interface stub.
+  // Example:
   //
-  // StubBindings(stub).connection - The Connection object that links an
-  //   optional proxy for a remote service to this stub. The value of
-  //   StubBindings(stub).connection.local == stub.
+  //    // FooImpl implements mojom.Foo.
+  //    function FooImpl() { ... }
+  //    FooImpl.prototype.fooMethod1 = function() { ... }
+  //    FooImpl.prototype.fooMethod2 = function() { ... }
   //
-  // StubBindings(stub).remote - A proxy for the the stub's Mojo client
-  //   service.
+  //    var fooPtr = new mojom.FooPtr();
+  //    var request = makeRequest(fooPtr);
+  //    var binding = new Binding(mojom.Foo, new FooImpl(), request);
+  //    fooPtr.fooMethod1();
+  function Binding(interfaceType, impl, request) {
+    this.interfaceType_ = interfaceType;
+    this.impl_ = impl;
+    this.stub_ = null;
+
+    if (request)
+      this.bind(request);
+  }
+
+  Binding.prototype.isBound = function() {
+    return this.stub_ !== null;
+  }
+
+  Binding.prototype.bind = function(request) {
+    this.close();
+    this.stub_ = connection.bindHandleToStub(request.handle,
+                                             this.interfaceType_);
+    connection.StubBindings(this.stub_).delegate = this.impl_;
+  }
 
-  function StubBindings(stub) {
-    return stub instanceof StubBase ?  stub[kStubProperties] : stub;
+  Binding.prototype.close = function() {
+    if (!this.isBound())
+      return;
+    connection.StubBindings(this.stub_).close();
+    this.stub_ = null;
   }
 
+  // TODO(yzshen): Implement the following methods.
+  //   Binding.prototype.setConnectionErrorHandler
+  //   Binding.prototype.unbind
+
   var exports = {};
-  exports.EmptyProxy = ProxyBase;
-  exports.EmptyStub = StubBase;
-  exports.ProxyBase = ProxyBase;
-  exports.ProxyBindings = ProxyBindings;
-  exports.StubBase = StubBase;
-  exports.StubBindings = StubBindings;
+  exports.InterfacePtrInfo = InterfacePtrInfo;
+  exports.InterfaceRequest = InterfaceRequest;
+  exports.makeRequest = makeRequest;
+  exports.InterfacePtrController = InterfacePtrController;
+  exports.Binding = Binding;
+
+  // TODO(yzshen): Remove the following exports.
+  exports.EmptyProxy = connection.EmptyProxy;
+  exports.EmptyStub = connection.EmptyStub;
+  exports.ProxyBase = connection.ProxyBase;
+  exports.ProxyBindings = connection.ProxyBindings;
+  exports.StubBase = connection.StubBase;
+  exports.StubBindings = connection.StubBindings;
+
   return exports;
 });

mojo/public/js/connection.js

@@ -3,20 +3,112 @@
 // found in the LICENSE file.
 
 define("mojo/public/js/connection", [
-  "mojo/public/js/bindings",
   "mojo/public/js/connector",
   "mojo/public/js/core",
   "mojo/public/js/router",
-], function(bindings, connector, core, router) {
+], function(connector, core, router) {
 
   var Router = router.Router;
-  var EmptyProxy = bindings.EmptyProxy;
-  var EmptyStub = bindings.EmptyStub;
-  var ProxyBindings = bindings.ProxyBindings;
-  var StubBindings = bindings.StubBindings;
   var TestConnector = connector.TestConnector;
   var TestRouter = router.TestRouter;
 
+  var kProxyProperties = Symbol("proxyProperties");
+  var kStubProperties = Symbol("stubProperties");
+
+  // Public proxy class properties that are managed at runtime by the JS
+  // bindings. See ProxyBindings below.
+  function ProxyProperties(receiver) {
+    this.receiver = receiver;
+  }
+
+  // TODO(hansmuller): remove then after 'Client=' has been removed from Mojom.
+  ProxyProperties.prototype.getLocalDelegate = function() {
+    return this.local && StubBindings(this.local).delegate;
+  }
+
+  // TODO(hansmuller): remove then after 'Client=' has been removed from Mojom.
+  ProxyProperties.prototype.setLocalDelegate = function(impl) {
+    if (this.local)
+      StubBindings(this.local).delegate = impl;
+    else
+      throw new Error("no stub object");
+  }
+
+  ProxyProperties.prototype.close = function() {
+    this.connection.close();
+  }
+
+  // Public stub class properties that are managed at runtime by the JS
+  // bindings. See StubBindings below.
+  function StubProperties(delegate) {
+    this.delegate = delegate;
+  }
+
+  StubProperties.prototype.close = function() {
+    this.connection.close();
+  }
+
+  // The base class for generated proxy classes.
+  function ProxyBase(receiver) {
+    this[kProxyProperties] = new ProxyProperties(receiver);
+
+    // TODO(hansmuller): Temporary, for Chrome backwards compatibility.
+    if (receiver instanceof Router)
+      this.receiver_ = receiver;
+  }
+
+  // The base class for generated stub classes.
+  function StubBase(delegate) {
+    this[kStubProperties] = new StubProperties(delegate);
+  }
+
+  // TODO(hansmuller): remove everything except the connection property doc
+  // after 'Client=' has been removed from Mojom.
+
+  // Provides access to properties added to a proxy object without risking
+  // Mojo interface name collisions. Unless otherwise specified, the initial
+  // value of all properties is undefined.
+  //
+  // ProxyBindings(proxy).connection - The Connection object that links the
+  //   proxy for a remote Mojo service to an optional local stub for a local
+  //   service. The value of ProxyBindings(proxy).connection.remote == proxy.
+  //
+  // ProxyBindings(proxy).local  - The "local" stub object whose delegate
+  //   implements the proxy's Mojo client interface.
+  //
+  // ProxyBindings(proxy).setLocalDelegate(impl) - Sets the implementation
+  //   delegate of the proxy's client stub object. This is just shorthand
+  //   for |StubBindings(ProxyBindings(proxy).local).delegate = impl|.
+  //
+  // ProxyBindings(proxy).getLocalDelegate() - Returns the implementation
+  //   delegate of the proxy's client stub object. This is just shorthand
+  //   for |StubBindings(ProxyBindings(proxy).local).delegate|.
+
+  function ProxyBindings(proxy) {
+    return (proxy instanceof ProxyBase) ? proxy[kProxyProperties] : proxy;
+  }
+
+  // TODO(hansmuller): remove the remote doc after 'Client=' has been
+  // removed from Mojom.
+
+  // Provides access to properties added to a stub object without risking
+  // Mojo interface name collisions. Unless otherwise specified, the initial
+  // value of all properties is undefined.
+  //
+  // StubBindings(stub).delegate - The optional implementation delegate for
+  //  the Mojo interface stub.
+  //
+  // StubBindings(stub).connection - The Connection object that links an
+  //   optional proxy for a remote service to this stub. The value of
+  //   StubBindings(stub).connection.local == stub.
+  //
+  // StubBindings(stub).remote - A proxy for the the stub's Mojo client
+  //   service.
+
+  function StubBindings(stub) {
+    return stub instanceof StubBase ?  stub[kStubProperties] : stub;
+  }
+
   // TODO(hansmuller): the proxy receiver_ property should be receiver$
 
   function BaseConnection(localStub, remoteProxy, router) {
@@ -184,6 +276,12 @@ define("mojo/public/js/connection", [
 
   var exports = {};
   exports.Connection = Connection;
+  exports.EmptyProxy = ProxyBase;
+  exports.EmptyStub = StubBase;
+  exports.ProxyBase = ProxyBase;
+  exports.ProxyBindings = ProxyBindings;
+  exports.StubBase = StubBase;
+  exports.StubBindings = StubBindings;
   exports.TestConnection = TestConnection;
 
   exports.bindProxy = bindProxy;

mojo/public/tools/bindings/generators/js_templates/interface_definition.tmpl

@@ -2,12 +2,21 @@
   var k{{interface.name}}_{{method.name}}_Name = {{method.ordinal}};
 {%- endfor %}
 
+  function {{interface.name}}Ptr() {
+    this.ptr = new bindings.InterfacePtrController({{interface.name}});
+  }
+
   function {{interface.name}}Proxy(receiver) {
     bindings.ProxyBase.call(this, receiver);
   }
   {{interface.name}}Proxy.prototype = Object.create(bindings.ProxyBase.prototype);
 
 {%- for method in interface.methods %}
+  {{interface.name}}Ptr.prototype.{{method.name|stylize_method}} = function() {
+    return {{interface.name}}Proxy.prototype.{{method.name|stylize_method}}
+        .apply(this.ptr.connection.remote, arguments);
+  };
+
   {{interface.name}}Proxy.prototype.{{method.name|stylize_method}} = function(
 {%- for parameter in method.parameters -%}
 {{parameter.name}}{% if not loop.last %}, {% endif %}

mojo/public/tools/bindings/generators/js_templates/module_definition.tmpl

@@ -40,6 +40,7 @@
 {%- endfor %}
 {%- for interface in interfaces %}
   exports.{{interface.name}} = {{interface.name}};
+  exports.{{interface.name}}Ptr = {{interface.name}}Ptr;
 {#--- Interface Client #}
 {%-   if interface.client in interfaces|map(attribute='name') %}
   exports.{{interface.name}}.client = {{interface.client}};