Implement Service & ServiceObject classes

lib/bigquery/dataset.js

@@ -22,19 +22,26 @@
 
 var extend = require('extend');
 var is = require('is');
+var nodeutil = require('util');
 
 /**
- * @type {module:bigquery/table}
+ * @type {module:common/serviceObject}
  * @private
  */
-var Table = require('./table.js');
+var ServiceObject = require('../common/service-object.js');
 
 /**
  * @type {module:common/streamrouter}
  * @private
  */
 var streamRouter = require('../common/stream-router.js');
 
+/**
+ * @type {module:bigquery/table}
+ * @private
+ */
+var Table = require('./table.js');
+
 /*! Developer Documentation
  *
  * @param {module:bigquery} bigQuery - BigQuery instance.
@@ -46,20 +53,121 @@ var streamRouter = require('../common/stream-router.js');
  *
  * @alias module:bigquery/dataset
  * @constructor
+ *
+ * @example
+ * var gcloud = require('gcloud');
+ *
+ * var bigquery = gcloud.bigquery({
+ *   keyFilename: '/path/to/keyfile.json',
+ *   projectId: 'grape-spaceship-123'
+ * });
+ * var dataset = bigquery.dataset('institutions');
  */
 function Dataset(bigQuery, id) {
+  var methods = {
+    /**
+     * Create a dataset.
+     *
+     * @example
+     * dataset.create(function(err, dataset, apiResponse) {
+     *   if (!err) {
+     *     // The dataset was created successfully.
+     *   }
+     * });
+     */
+    create: true,
+
+    /**
+     * Check if the dataset exists.
+     *
+     * @param {function} callback - The callback function.
+     * @param {?error} callback.err - An error returned while making this
+     *     request.
+     * @param {boolean} callback.exists - Whether the dataset exists or not.
+     *
+     * @example
+     * dataset.exists(function(err, exists) {});
+     */
+    exists: true,
+
+    /**
+     * Get a dataset if it exists.
+     *
+     * You may optionally use this to "get or create" an object by providing an
+     * object with `autoCreate` set to `true`. Any extra configuration that is
+     * normally required for the `create` method must be contained within this
+     * object as well.
+     *
+     * @param {options=} options - Configuration object.
+     * @param {boolean} options.autoCreate - Automatically create the object if
+     *     it does not exist. Default: `false`
+     *
+     * @example
+     * dataset.get(function(err, dataset, apiResponse) {
+     *   if (!err) {
+     *     // `dataset.metadata` has been populated.
+     *   }
+     * });
+     */
+    get: true,
+
+    /**
+     * Get the metadata for the Dataset.
+     *
+     * @resource [Datasets: get API Documentation]{@link https://cloud.google.com/bigquery/docs/reference/v2/datasets/get}
+     *
+     * @param {function} callback - The callback function.
+     * @param {?error} callback.err - An error returned while making this
+     *     request.
+     * @param {object} callback.metadata - The dataset's metadata.
+     * @param {object} callback.apiResponse - The full API response.
+     *
+     * @example
+     * dataset.getMetadata(function(err, metadata, apiResponse) {});
+     */
+    getMetadata: true,
+
+    /**
+     * Sets the metadata of the Dataset object.
+     *
+     * @resource [Datasets: patch API Documentation]{@link https://cloud.google.com/bigquery/docs/reference/v2/datasets/patch}
+     *
+     * @param {object} metadata - Metadata to save on the Dataset.
+     * @param {function} callback - The callback function.
+     * @param {?error} callback.err - An error returned while making this
+     *     request.
+     * @param {object} callback.apiResponse - The full API response.
+     *
+     * @example
+     * var metadata = {
+     *   description: 'Info for every institution in the 2013 IPEDS universe'
+     * };
+     *
+     * dataset.setMetadata(metadata, function(err, apiResponse) {});
+     */
+    setMetadata: true
+  };
+
+  ServiceObject.call(this, {
+    parent: bigQuery,
+    baseUrl: '/datasets',
+    id: id,
+    createMethod: bigQuery.createDataset.bind(bigQuery),
+    methods: methods
+  });
+
   this.bigQuery = bigQuery;
-  this.id = id;
-  this.metadata = {};
 }
 
+nodeutil.inherits(Dataset, ServiceObject);
+
 /**
  * Create a table given a tableId or configuration object.
  *
  * @resource [Tables: insert API Documentation]{@link https://cloud.google.com/bigquery/docs/reference/v2/tables/insert}
  *
- * @param {object} options - Table id or configuration object.
- * @param {string} options.id - The id of the table.
+ * @param {string} id - Table id.
+ * @param {object=} options - Configuration object.
  * @param {string|object} options.schema - A comma-separated list of name:type
  *     pairs. Valid types are "string", "integer", "float", "boolean", and
  *     "timestamp". If the type is omitted, it is assumed to be "string".
@@ -79,37 +187,39 @@ function Dataset(bigQuery, id) {
  *   schema: 'UNITID,INSTNM,ADDR,CITY,STABBR,ZIP,FIPS,OBEREG,CHFNM,...'
  * };
  *
- * var bigquery = gcloud.bigquery({
- *   projectId: 'grape-spaceship-123'
- * });
- * var dataset = bigquery.dataset();
- *
  * dataset.createTable(tableConfig, function(err, table, apiResponse) {});
  */
-Dataset.prototype.createTable = function(options, callback) {
-  var that = this;
+Dataset.prototype.createTable = function(id, options, callback) {
+  var self = this;
+
+  if (is.fn(options)) {
+    callback = options;
+    options = {};
+  }
 
   extend(true, options, {
     tableReference: {
       datasetId: this.id,
       projectId: this.bigQuery.projectId,
-      tableId: options.id
+      tableId: id
     }
   });
 
   if (is.string(options.schema)) {
     options.schema = Table.createSchemaFromString_(options.schema);
   }
 
-  delete options.id;
-
-  this.makeReq_('POST', '/tables', null, options, function(err, resp) {
+  this.request({
+    method: 'POST',
+    uri: '/tables',
+    json: options
+  }, function(err, resp) {
     if (err) {
       callback(err, null, resp);
       return;
     }
 
-    var table = that.table(resp.tableReference.tableId);
+    var table = self.table(resp.tableReference.tableId);
     table.metadata = resp;
 
     callback(null, table, resp);
@@ -149,34 +259,11 @@ Dataset.prototype.delete = function(options, callback) {
     deleteContents: !!options.force
   };
 
-  this.makeReq_('DELETE', '', query, null, callback);
-};
-
-/**
- * Get the metadata for the Dataset.
- *
- * @resource [Datasets: get API Documentation]{@link https://cloud.google.com/bigquery/docs/reference/v2/datasets/get}
- *
- * @param {function} callback - The callback function.
- * @param {?error} callback.err - An error returned while making this request
- * @param {object} callback.metadata - The dataset's metadata.
- * @param {object} callback.apiResponse - The full API response.
- *
- * @example
- * dataset.getMetadata(function(err, metadata, apiResponse) {});
- */
-Dataset.prototype.getMetadata = function(callback) {
-  var that = this;
-  this.makeReq_('GET', '', null, null, function(err, resp) {
-    if (err) {
-      callback(err, null, resp);
-      return;
-    }
-
-    that.metadata = resp;
-
-    callback(null, that.metadata, resp);
-  });
+  this.request({
+    method: 'DELETE',
+    uri: '',
+    qs: query
+  }, callback);
 };
 
 /**
@@ -231,14 +318,16 @@ Dataset.prototype.getTables = function(query, callback) {
 
   query = query || {};
 
-  this.makeReq_('GET', '/tables', query, null, function(err, resp) {
+  this.request({
+    uri: '/tables',
+    qs: query
+  }, function(err, resp) {
     if (err) {
       callback(err, null, null, resp);
       return;
     }
 
     var nextQuery = null;
-
     if (resp.nextPageToken) {
       nextQuery = extend({}, query, {
         pageToken: resp.nextPageToken
@@ -277,39 +366,7 @@ Dataset.prototype.query = function(options, callback) {
 };
 
 /**
- * Sets the metadata of the Dataset object.
- *
- * @resource [Datasets: patch API Documentation]{@link https://cloud.google.com/bigquery/docs/reference/v2/datasets/patch}
- *
- * @param {object} metadata - Metadata to save on the Dataset.
- * @param {function} callback - The callback function.
- * @param {?error} callback.err - An error returned while making this request
-  * @param {object} callback.apiResponse - The full API response.
- *
- * @example
- * var metadata = {
- *   description: 'Information for every institution in the 2013 IPEDS universe'
- * };
- *
- * dataset.setMetadata(metadata, function(err, apiResponse) {});
- */
-Dataset.prototype.setMetadata = function(metadata, callback) {
-  var that = this;
-
-  this.makeReq_('PATCH', '', null, metadata, function(err, resp) {
-    if (err) {
-      callback(err, resp);
-      return;
-    }
-
-    that.metadata = resp;
-
-    callback(null, resp);
-  });
-};
-
-/**
- * Return a new instance of reference to an existing Table object.
+ * Create a Table object.
  *
  * @param {string} id - The ID of the table.
  * @return {module:bigquery/table}
@@ -321,28 +378,11 @@ Dataset.prototype.table = function(id) {
   return new Table(this, id);
 };
 
-/**
- * Pass through this request to BigQuery's request handler, first prepending the
- * path with the dataset.
- *
- * @private
- *
- * @param {string} method - Action.
- * @param {string} path - Request path.
- * @param {*} query - Request query object.
- * @param {*} body - Request body contents.
- * @param {function} callback - The callback function.
- */
-Dataset.prototype.makeReq_ = function(method, path, query, body, callback) {
-  path = '/datasets/' + this.id + path;
-  this.bigQuery.makeReq_(method, path, query, body, callback);
-};
-
 /*! Developer Documentation
  *
  * These methods can be used with either a callback or as a readable object
  * stream. `streamRouter` is used to add this dual behavior.
  */
-streamRouter.extend(Dataset, 'getTables');
+streamRouter.extend(Dataset, ['getTables']);
 
 module.exports = Dataset;