Get rid of the Name class (breaking)

Move exporting interfaces directly onto the bus.

Remove the `NameExistsError`.

fixes #22

Author: Tony Crisci

.gitignore

@@ -17,3 +17,6 @@ results
 node_modules
 npm-debug.log
 package-lock.json
+
+*.swp
+*.swo

README.md

@@ -151,17 +151,17 @@ setTimeout(() => {
 
 async function main() {
   // make a request for the name on the bus
-  let name = await bus.requestName('org.test.name');
-  // export the interface on the name
-  name.export('/org/test/path', example);
+  await bus.requestName('org.test.name');
+  // export the interface on the path
+  bus.export('/org/test/path', example);
 }
 
 main().catch((err) => {
   console.log('Error: ' + err);
 });
 ```
 
-Interfaces extend the `Interface` class. Declare service methods, properties, and signals with the decorators provided from the library. First request a name on the bus with `bus.requestName()`. Then call `name.export()` with the path and interface to expose this interface on the bus.
+Interfaces extend the `Interface` class. Declare service methods, properties, and signals with the decorators provided from the library. You can optionally request a name on the bus with `bus.requestName()` so clients have a well-known name to connect to. Then call `bus.export()` with the path and interface to expose this interface on the bus.
 
 Methods are called when a DBus client calls that method on the server. Properties can be gotten and set with the `org.freedesktop.DBus.Properties` interface and are included in the introspection xml.
 

examples/service/index.js

@@ -78,9 +78,9 @@ setTimeout(() => {
 }, 500);
 
 async function main() {
-  let name = await bus.requestName('org.test.name');
-  name.export('/org/test/path', example);
-  name.export('/org/test/path', example2);
+  await bus.requestName('org.test.name');
+  bus.export('/org/test/path', example);
+  bus.export('/org/test/path', example2);
 }
 
 main().catch((err) => {

index.js

@@ -61,14 +61,88 @@ module.exports.DBUS_NAME_FLAG_REPLACE_EXISTING = constants.DBUS_NAME_FLAG_REPLAC
 
 /**
  * A flag for {@link MessageBus#requestName} to indicate this request should
- * not enter the queue of clients requesting this name if it is taken. The
- * request may fail with {@link NameExistsError} in this case.
+ * not enter the queue of clients requesting this name if it is taken.
  *
  * @see {@link https://dbus.freedesktop.org/doc/dbus-specification.html#bus-messages-request-name}
  * @constant DBUS_NAME_FLAG_DO_NOT_QUEUE
  */
 module.exports.DBUS_NAME_FLAG_DO_NOT_QUEUE = constants.DBUS_NAME_FLAG_DO_NOT_QUEUE;
 
+/**
+ * An enum for the return value of {@link MessageBus#requestName} to indicate
+ * the caller is now the primary owner of the name, replacing any previous
+ * owner.
+ *
+ * @see {@link https://dbus.freedesktop.org/doc/dbus-specification.html#bus-messages-request-name}
+ * @constant DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER
+ */
+module.exports.DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER = constants.DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER;
+
+/**
+ * An enum for the return value of {@link MessageBus#requestName} to indicate
+ * the name already had an owner, `DBUS_NAME_FLAG_DO_NOT_QUEUE` was not
+ * specified, and either the current owner did not specify
+ * `DBUS_NAME_FLAG_ALLOW_REPLACEMENT` or the requesting application did not
+ * specify `DBUS_NAME_FLAG_REPLACE_EXISTING`.
+ *
+ * @see {@link https://dbus.freedesktop.org/doc/dbus-specification.html#bus-messages-request-name}
+ * @constant DBUS_REQUEST_NAME_REPLY_IN_QUEUE
+ */
+module.exports.DBUS_REQUEST_NAME_REPLY_IN_QUEUE = constants.DBUS_REQUEST_NAME_REPLY_IN_QUEUE;
+
+/**
+ * An enum for the return value of {@link MessageBus#requestName} to indicate
+ * the name already has an owner, `DBUS_NAME_FLAG_DO_NOT_QUEUE` was specified,
+ * and either `DBUS_NAME_FLAG_ALLOW_REPLACEMENT` was not specified by the
+ * current owner, or `DBUS_NAME_FLAG_REPLACE_EXISTING` was not specified by the
+ * requesting application.
+ *
+ * @see {@link https://dbus.freedesktop.org/doc/dbus-specification.html#bus-messages-request-name}
+ * @constant DBUS_REQUEST_NAME_REPLY_EXISTS
+ */
+module.exports.DBUS_REQUEST_NAME_REPLY_EXISTS = constants.DBUS_REQUEST_NAME_REPLY_EXISTS;
+
+/**
+ * An enum for the return value of {@link MessageBus#requestName} to indicate
+ * the application trying to request ownership of a name is already the owner
+ * of it.
+ *
+ * @see {@link https://dbus.freedesktop.org/doc/dbus-specification.html#bus-messages-request-name}
+ * @constant DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER
+ */
+module.exports.DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER = constants.DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER;
+
+/**
+ * An enumn for the return value of {@link MessageBus#releaseName} to indicate
+ * the caller has released his claim on the given name. Either the caller was
+ * the primary owner of the name, and the name is now unused or taken by
+ * somebody waiting in the queue for the name, or the caller was waiting in the
+ * queue for the name and has now been removed from the queue.
+ *
+ * @see {@link https://dbus.freedesktop.org/doc/dbus-specification.html#bus-messages-release-name}
+ * @constant DBUS_RELEASE_NAME_REPLY_RELEASED
+ */
+module.exports.DBUS_RELEASE_NAME_REPLY_RELEASED = constants.DBUS_RELEASE_NAME_REPLY_RELEASED;
+
+/**
+ * An enumn for the return value of {@link MessageBus#releaseName} to indicate
+ * the given name does not exist on this bus.
+ *
+ * @see {@link https://dbus.freedesktop.org/doc/dbus-specification.html#bus-messages-release-name}
+ * @constant DBUS_RELEASE_NAME_REPLY_NON_EXISTENT
+ */
+module.exports.DBUS_RELEASE_NAME_REPLY_NON_EXISTENT = constants.DBUS_RELEASE_NAME_REPLY_NON_EXISTENT;
+
+/**
+ * An enumn for the return value of {@link MessageBus#releaseName} to indicate
+ * the caller was not the primary owner of this name, and was also not waiting
+ * in the queue to own this name.
+ *
+ * @see {@link https://dbus.freedesktop.org/doc/dbus-specification.html#bus-messages-release-name}
+ * @constant DBUS_RELEASE_NAME_REPLY_NOT_OWNER
+ */
+module.exports.DBUS_RELEASE_NAME_REPLY_NOT_OWNER = constants.DBUS_RELEASE_NAME_REPLY_NOT_OWNER;
+
 /**
  * An enum value for the {@link Message} `type` member to indicate the message
  * is a method call.
@@ -139,4 +213,3 @@ module.exports.Variant = Variant;
 module.exports.Message = Message;
 module.exports.validators = require('./lib/validators');
 module.exports.DBusError = errors.DBusError;
-module.exports.NameExistsError = errors.NameExistsError;

lib/bus.js

@@ -1,10 +1,10 @@
 const EventEmitter = require('events').EventEmitter;
 const constants = require('./constants');
 const handleMethod = require('./service/handlers');
-const { NameExistsError } = require('./errors');
-const Name = require('./service/name');
 const {DBusError} = require('./errors');
 const {Message} = require('./message-type');
+const ServiceObject = require('./service/object');
+const xml2js = require('xml2js');
 
 let {
   assertBusNameValid,
@@ -15,6 +15,8 @@ let {
 let ProxyObject = require('./client/proxy-object');
 let { Interface } = require('./service/interface');
 
+const xmlHeader = `<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">\n`
+
 /**
  * @class
  * The `MessageBus` is a class for interacting with a DBus message bus capable
@@ -37,8 +39,8 @@ let { Interface } = require('./service/interface');
  * const bus = dbus.sessionBus();
  * // get a proxy object
  * let obj = await bus.getProxyObject('org.freedesktop.DBus', '/org/freedesktop/DBus');
- * // request a service name
- * let name = await bus.requestName('org.test.name');
+ * // request a well-known name
+ * await bus.requestName('org.test.name');
  */
 class MessageBus extends EventEmitter {
   /**
@@ -48,13 +50,14 @@ class MessageBus extends EventEmitter {
    */
   constructor(conn) {
     super();
+    this._builder = new xml2js.Builder({ headless: true });
     this._connection = conn;
     this._serial = 1;
     this._methodReturnHandlers = {};
     this._signals = new EventEmitter();
-    this._names = {};
     this._nameOwners = {};
     this._methodHandlers = [];
+    this._serviceObjects = {}
     /**
      * The unique name of the bus connection. This will be `null` until the
      * `MessageBus` is connected.
@@ -139,7 +142,6 @@ class MessageBus extends EventEmitter {
     this.call(helloMessage)
       .then((msg) => {
         this.name = msg.body[0];
-        // TODO document this signal
         this.emit('connect');
       })
       .catch((err) => {
@@ -164,20 +166,13 @@ class MessageBus extends EventEmitter {
   };
 
   /**
-   * Request a well-known [`Name`]{@link module:interface~Name} on the bus. The
-   * `Name` can be used to export an [`Interface`]{@link
-   * module:interface~Interface} at an object path on the name. If the name is
-   * already taken and {@link DBUS_NAME_FLAG_DO_NOT_QUEUE} is given, the method
-   * may throw a {@link NameExistsError}. See {@link
-   * DBUS_NAME_FLAG_ALLOW_REPLACEMENT} and {@link
-   * DBUS_NAME_FLAG_REPLACE_EXISTING} for more information on the other name
-   * flags.
+   * Request a well-known name on the bus.
+   *
    * @see {@link https://dbus.freedesktop.org/doc/dbus-specification.html#bus-messages-request-name}
    *
    * @param name {string} - the well-known name on the bus to request.
    * @param flags {NameFlags} - DBus name flags which affect the behavior of taking the name.
-   * @returns {Promise} - a Promise that resolves with the [`Name`]{@link
-   * module:interface~Name}.
+   * @returns {Promise} - a Promise that resolves with the `RequestNameReply`.
    */
   requestName(name, flags) {
     flags = flags || 0;
@@ -193,25 +188,41 @@ class MessageBus extends EventEmitter {
       });
       this.call(requestNameMessage)
         .then((msg) => {
-          let result = msg.body[0];
-          if (result === constants.DBUS_REQUEST_NAME_REPLY_EXISTS) {
-            return reject(new NameExistsError(`the name already exists: ${name}`));
-          }
-          if (this._names[name]) {
-            let nameObj = this._names[name];
-            nameObj.flags = flags;
-            return resolve(nameObj);
-          }
-          let nameObj = new Name(this, name, flags);
-          this._names[name] = nameObj;
-          return resolve(nameObj);
+          return resolve(msg.body[0]);
         })
         .catch((err) => {
           return reject(err);
         });
     });
   }
 
+  /**
+   * Release this name. Requests that the name should no longer be owned by the
+   * {@link MessageBus}.
+   *
+   * @returns {Promise} A Promise that will resolve with the `ReleaseNameReply`.
+   */
+  releaseName(name) {
+    return new Promise((resolve, reject) => {
+      let msg = new Message({
+        path: '/org/freedesktop/DBus',
+        destination: 'org.freedesktop.DBus',
+        interface: 'org.freedesktop.DBus',
+        member: 'ReleaseName',
+        signature: 's',
+        body: [name]
+      });
+      this.call(msg)
+        .then((reply) => {
+          return resolve(reply.body[0]);
+        })
+        .catch((err) => {
+          return reject(err);
+        });
+    });
+  }
+
+
   /**
    * Disconnect this `MessageBus` from the bus.
    */
@@ -333,6 +344,90 @@ class MessageBus extends EventEmitter {
     this._connection.message(msg);
   }
 
+  /**
+   * Export an [`Interface`]{@link module:interface~Interface} on the bus. See
+   * the documentation for that class for how to define service interfaces.
+   *
+   * @param path {string} - The object path to export this `Interface` on.
+   * @param iface {module:interface~Interface} - The service interface to export.
+   */
+  export(path, iface) {
+    let obj = this._getServiceObject(path);
+    obj.addInterface(iface);
+  }
+
+  /**
+   * Unexport an `Interface` on the bus. The interface will no longer be
+   * advertised to clients.
+   *
+   * @param {string} path - The object path on which to unexport.
+   * @param {module:interface~Interface} [iface] - The `Interface` to unexport.
+   * If not given, this will remove all interfaces on the path.
+   */
+  unexport(path, iface) {
+    iface = iface || null;
+    if (iface === null) {
+      this._removeServiceObject(path);
+    } else {
+      let obj = this._getServiceObject(path);
+      obj.removeInterface(iface);
+      if (!obj.interfaces.length) {
+        this._removeServiceObject(path);
+      }
+    }
+  }
+
+  _introspect(path) {
+    assertObjectPathValid(path);
+    let xml = {
+      node: {
+        node: []
+      }
+    };
+
+    if (this._serviceObjects[path]) {
+      xml.node.interface = this._serviceObjects[path].introspect();
+    }
+
+    let pathSplit = path.split('/').filter(n => n);
+
+    for (let key of Object.keys(this._serviceObjects)) {
+      let keySplit = key.split('/').filter(n => n);
+      if (keySplit.length <= pathSplit.length) {
+        continue;
+      }
+      if (pathSplit.every((v, i) => v === keySplit[i])) {
+        let child = keySplit[pathSplit.length];
+        xml.node.node.push({
+          $: {
+            name: child
+          }
+        });
+      }
+    }
+
+    return xmlHeader + this._builder.buildObject(xml);
+  }
+
+  _getServiceObject(path) {
+    assertObjectPathValid(path);
+    if (!this._serviceObjects[path]) {
+      this._serviceObjects[path] = new ServiceObject(path, this);
+    }
+    return this._serviceObjects[path];
+  }
+
+  _removeServiceObject(path) {
+    assertObjectPathValid(path);
+    if (this._serviceObjects[path]) {
+      let obj = this._serviceObjects[path];
+      for (let i of Object.keys(obj.interfaces)) {
+        obj.removeInterface(obj.interfaces[i]);
+      }
+      delete this._serviceObjects[path];
+    }
+  }
+
   _addMatch(match) {
     let msg = new Message({
       path: '/org/freedesktop/DBus',

lib/constants.js

@@ -15,6 +15,11 @@ module.exports = {
   DBUS_REQUEST_NAME_REPLY_EXISTS: 3,
   DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER: 4,
 
+  // the result of bus.releaseName()
+  DBUS_RELEASE_NAME_REPLY_RELEASED: 1,
+  DBUS_RELEASE_NAME_REPLY_NON_EXISTENT: 2,
+  DBUS_RELEASE_NAME_REPLY_NOT_OWNER: 3,
+
   messageType: {
     INVALID: 0,
     METHOD_CALL: 1,

lib/errors.js

@@ -26,23 +26,6 @@ class DBusError extends Error {
   }
 }
 
-/**
- * An error that can be thrown when trying to request a name with {@link
- * MessageBus#requestName} when the {@link DBUS_NAME_FLAG_DO_NOT_QUEUE} flag is
-  * given.
- */
-class NameExistsError extends Error {
-  /**
-   * Create a `NameExistsError`. This constructor should not be called directly.
-   */
-  constructor(message) {
-    message = message || 'Requested a name that already exists on the bus';
-    super(message);
-    this.name = 'NameExistsError';
-  }
-}
-
 module.exports = {
   DBusError: DBusError,
-  NameExistsError: NameExistsError,
 };