Marionette JS Client

API Docs for: 1.7.1
Show:

File: lib/marionette/drivers/abstract.js

  1. (function(module, ns) {

  3.   /**
  4.    *
  5.    * Abstract driver that will handle
  6.    * all common tasks between implementations.
  7.    * Such as error handling, request/response queuing
  8.    * and timeouts.
  9.    *
  10.    * @constructor
  11.    * @class Marionette.Drivers.Abstract
  12.    * @param {Object} options set options on prototype.
  13.    */
  14.   function Abstract(options) {
  15.     this._sendQueue = [];
  16.     this._responseQueue = [];
  17.   }

  19.   Abstract.prototype = {

  21.     /**
  22.      * Timeout for commands
  23.      *
  24.      * @property timeout
  25.      * @type Numeric
  26.      */
  27.     timeout: 10000,

  29.     /**
  30.      * Waiting for a command to finish?
  31.      *
  32.      * @private
  33.      * @property _waiting
  34.      * @type Boolean
  35.      */
  36.     _waiting: true,

  38.     /**
  39.      * Is system ready for commands?
  40.      *
  41.      * @property ready
  42.      * @type Boolean
  43.      */
  44.     ready: false,

  46.     /**
  47.      * Connection id for the server.
  48.      *
  49.      * @property connectionId
  50.      * @type Numeric
  51.      */
  52.     connectionId: null,

  54.     /**
  55.      * We just set the script timeout.
  56.      * If you need to do something in the driver.
  57.      *
  58.      * @method setScriptTiemout
  59.      * @param {Integer} the timeout value.
  60.      */
  61.     setScriptTimeout: function setScriptTimeout(timeout) {
  62.     },

  64.     /**
  65.      * Sends remote command to server.
  66.      * Each command will be queued while waiting for
  67.      * any pending commands. This ensures order of
  68.      * response is correct.
  69.      *
  70.      *
  71.      * @method send
  72.      * @param {Object} command remote command to send to marionette.
  73.      * @param {Function} callback executed when response comes back.
  74.      */
  75.     send: function send(cmd, callback) {
  76.       if (!this.ready) {
  77.         throw new Error('connection is not ready');
  78.       }

  80.       if (typeof(callback) === 'undefined') {
  81.         throw new Error('callback is required');
  82.       }

  84.       this._responseQueue.push(callback);
  85.       this._sendQueue.push(cmd);

  87.       this._nextCommand();

  89.       return this;
  90.     },

  92.     /**
  93.      * Connects to a remote server.
  94.      * Requires a _connect function to be defined.
  95.      *
  96.      *     MyClass.prototype._connect = function _connect(){
  97.      *       //open a socket to marrionete accept response
  98.      *       //you *must* call _onDeviceResponse with the first
  99.      *       //response from marionette it looks like this:
  100.      *       //{ from: 'root', applicationType: 'gecko', traits: [] }
  101.      *       this.connectionId = result.id;
  102.      *     }
  103.      *
  104.      * @method connect
  105.      * @param {Function} callback executes
  106.      *   after successfully connecting to the server.
  107.      */
  108.     connect: function connect(callback) {
  109.       this.ready = true;
  110.       this._responseQueue.push(function(data) {
  111.         this.applicationType = data.applicationType;
  112.         this.traits = data.traits;
  113.         callback();
  114.       }.bind(this));
  115.       this._connect();
  116.     },

  118.     /**
  119.      * Destroys connection to server
  120.      *
  121.      * Will immediately close connection to server
  122.      * closing any pending responses.
  123.      *
  124.      * @method close
  125.      */
  126.     close: function() {
  127.       this.ready = false;
  128.       this._responseQueue.length = 0;
  129.       if (this._close) {
  130.         this._close();
  131.       }
  132.     },

  134.     /**
  135.      * Checks queue if not waiting for a response
  136.      * Sends command to websocket server
  137.      *
  138.      * @private
  139.      * @method _nextCommand
  140.      */
  141.     _nextCommand: function _nextCommand() {
  142.       var nextCmd;
  143.       if (!this._waiting && this._sendQueue.length) {
  144.         this._waiting = true;
  145.         nextCmd = this._sendQueue.shift();
  146.         this._sendCommand(nextCmd);
  147.       }
  148.     },

  150.     /**
  151.      * Handles responses from devices.
  152.      * Will only respond to the event if the connectionId
  153.      * is equal to the event id and the client is ready.
  154.      *
  155.      * @param {Object} data response from server.
  156.      * @private
  157.      * @method _onDeviceResponse
  158.      */
  159.     _onDeviceResponse: function _onDeviceResponse(data) {
  160.       var cb;
  161.       if (this.ready && data.id === this.connectionId) {
  162.         this._waiting = false;
  163.         cb = this._responseQueue.shift();
  164.         cb(data.response);

  166.         this._nextCommand();
  167.       }
  168.     }

  170.   };

  172.   module.exports = Abstract;

  174. }.apply(
  175.   this,
  176.   (this.Marionette) ?
  177.     [Marionette('drivers/abstract'), Marionette] :
  178.     [module, require('../marionette')]
  179. ));

  181.