You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by ja...@apache.org on 2011/04/16 21:32:26 UTC
svn commit: r1094035 - /couchdb/trunk/share/www/script/jquery.couch.js
Author: jan
Date: Sat Apr 16 19:32:26 2011
New Revision: 1094035
URL: http://svn.apache.org/viewvc?rev=1094035&view=rev
Log:
Add inline documentation for jquery.couch.js
Closes COUCHDB-1116
Patch by Dale Harvey.
Modified:
couchdb/trunk/share/www/script/jquery.couch.js
Modified: couchdb/trunk/share/www/script/jquery.couch.js
URL: http://svn.apache.org/viewvc/couchdb/trunk/share/www/script/jquery.couch.js?rev=1094035&r1=1094034&r2=1094035&view=diff
==============================================================================
--- couchdb/trunk/share/www/script/jquery.couch.js [utf-8] (original)
+++ couchdb/trunk/share/www/script/jquery.couch.js [utf-8] Sat Apr 16 19:32:26 2011
@@ -10,9 +10,38 @@
// License for the specific language governing permissions and limitations under
// the License.
+/**
+ * @namespace
+ * $.couch is used to communicate with a CouchDB server, the server methods can
+ * be called directly without creating an instance. Typically all methods are
+ * passed an <code>options</code> object which defines a success callback which
+ * is called with the data returned from the http request to CouchDB, you can
+ * find the other settings that can be used in the <code>options</code> object
+ * from <a href="http://api.jquery.com/jQuery.ajax/#jQuery-ajax-settings">
+ * jQuery.ajax settings</a>
+ * <pre><code>$.couch.activeTasks({
+ * success: function (data) {
+ * console.log(data);
+ * }
+ * });</code></pre>
+ * Outputs (for example):
+ * <pre><code>[
+ * {
+ * "pid" : "<0.11599.0>",
+ * "status" : "Copied 0 of 18369 changes (0%)",
+ * "task" : "recipes",
+ * "type" : "Database Compaction"
+ * }
+ *]</code></pre>
+ */
(function($) {
+
$.couch = $.couch || {};
+ /** @lends $.couch */
+ /**
+ * @private
+ */
function encodeDocId(docID) {
var parts = docID.split("/");
if (parts[0] == "_design") {
@@ -20,8 +49,11 @@
return "_design/" + encodeURIComponent(parts.join('/'));
}
return encodeURIComponent(docID);
- };
+ }
+ /**
+ * @private
+ */
function prepareUserDoc(user_doc, new_password) {
if (typeof hex_sha1 == "undefined") {
alert("creating a user doc requires sha1.js to be loaded in the page");
@@ -39,12 +71,23 @@
user_doc.roles = [];
}
return user_doc;
- };
+ }
var uuidCache = [];
$.extend($.couch, {
urlPrefix: '',
+
+ /**
+ * You can obtain a list of active tasks by using the /_active_tasks URL.
+ * The result is a JSON array of the currently running tasks, with each task
+ * being described with a single object.
+ * @see <a href="http://techzone.couchbase.com/sites/default/files/uploads/
+ * all/documentation/couchbase-api-misc.html#couchbase-api-misc_active-task
+ * s_get">docs for /_active_tasks</a>
+ * @param {ajaxSettings} options <a href="http://api.jquery.com/jQuery.ajax
+ * /#jQuery-ajax-settings">jQuery ajax settings</a>
+ */
activeTasks: function(options) {
ajax(
{url: this.urlPrefix + "/_active_tasks"},
@@ -53,6 +96,14 @@
);
},
+ /**
+ * Returns a list of all the databases in the CouchDB instance
+ * @see <a href="http://techzone.couchbase.com/sites/default/files/uploads/
+ * all/documentation/couchbase-api-misc.html#couchbase-api-misc_active-task
+ * s_get">docs for /_all_dbs</a>
+ * @param {ajaxSettings} options <a href="http://api.jquery.com/jQuery.ajax
+ * /#jQuery-ajax-settings">jQuery ajax settings</a>
+ */
allDbs: function(options) {
ajax(
{url: this.urlPrefix + "/_all_dbs"},
@@ -61,6 +112,21 @@
);
},
+ /**
+ * View and edit the CouchDB configuration, called with just the options
+ * parameter the entire config is returned, you can be more specific by
+ * passing the section and option parameters, if you specify a value that
+ * value will be stored in the configuration.
+ * @see <a href="http://techzone.couchbase.com/sites/default/files/uploads/
+ * all/documentation/couchbase-api-config.html#couchbase-api-config_config
+ * -section-key_put">docs for /_config</a>
+ * @param {ajaxSettings} options
+ * <a href="http://api.jquery.com/jQuery.ajax/#jQuery-ajax-settings">
+ * jQuery ajax settings</a>
+ * @param {String} [section] the section of the config
+ * @param {String} [option] the particular config option
+ * @param {String} [value] value to be set
+ */
config: function(options, section, option, value) {
var req = {url: this.urlPrefix + "/_config/"};
if (section) {
@@ -83,6 +149,12 @@
);
},
+ /**
+ * Returns the session information for the currently logged in user.
+ * @param {ajaxSettings} options
+ * <a href="http://api.jquery.com/jQuery.ajax/#jQuery-ajax-settings">
+ * jQuery ajax settings</a>
+ */
session: function(options) {
options = options || {};
$.ajax({
@@ -103,6 +175,9 @@
});
},
+ /**
+ * @private
+ */
userDb : function(callback) {
$.couch.session({
success : function(resp) {
@@ -112,6 +187,17 @@
});
},
+ /**
+ * Create a new user on the CouchDB server, <code>user_doc</code> is an
+ * object with a <code>name</code> field and other information you want
+ * to store relating to that user, for example
+ * <code>{"name": "daleharvey"}</code>
+ * @param {Object} user_doc Users details
+ * @param {String} password Users password
+ * @param {ajaxSettings} options
+ * <a href="http://api.jquery.com/jQuery.ajax/#jQuery-ajax-settings">
+ * jQuery ajax settings</a>
+ */
signup: function(user_doc, password, options) {
options = options || {};
// prepare user doc based on name and password
@@ -121,6 +207,13 @@
});
},
+ /**
+ * Authenticate against CouchDB, the <code>options</code> parameter is
+ *expected to have <code>name</code> and <code>password</code> fields.
+ * @param {ajaxSettings} options
+ * <a href="http://api.jquery.com/jQuery.ajax/#jQuery-ajax-settings">
+ * jQuery ajax settings</a>
+ */
login: function(options) {
options = options || {};
$.ajax({
@@ -141,6 +234,14 @@
}
});
},
+
+
+ /**
+ * Delete your current CouchDB user session
+ * @param {ajaxSettings} options
+ * <a href="http://api.jquery.com/jQuery.ajax/#jQuery-ajax-settings">
+ * jQuery ajax settings</a>
+ */
logout: function(options) {
options = options || {};
$.ajax({
@@ -162,14 +263,27 @@
});
},
+ /**
+ * @namespace
+ * $.couch.db is used to communicate with a specific CouchDB database
+ * <pre><code>var $db = $.couch.db("mydatabase");
+ *$db.allApps({
+ * success: function (data) {
+ * ... process data ...
+ * }
+ *});
+ * </code></pre>
+ */
db: function(name, db_opts) {
db_opts = db_opts || {};
var rawDocs = {};
function maybeApplyVersion(doc) {
- if (doc._id && doc._rev && rawDocs[doc._id] && rawDocs[doc._id].rev == doc._rev) {
+ if (doc._id && doc._rev && rawDocs[doc._id] &&
+ rawDocs[doc._id].rev == doc._rev) {
// todo: can we use commonjs require here?
if (typeof Base64 == "undefined") {
- alert("please include /_utils/script/base64.js in the page for base64 support");
+ alert("please include /_utils/script/base64.js in the page for " +
+ "base64 support");
return false;
} else {
doc._attachments = doc._attachments || {};
@@ -181,10 +295,19 @@
}
}
};
- return {
+ return /** @lends $.couch.db */{
name: name,
uri: this.urlPrefix + "/" + encodeURIComponent(name) + "/",
+ /**
+ * Request compaction of the specified database.
+ * @see <a href="http://techzone.couchbase.com/sites/default/files/
+ * uploads/all/documentation/couchbase-api-db.html#couchbase-api-db_
+ * db-compact_post">docs for /db/_compact</a>
+ * @param {ajaxSettings} options
+ * <a href="http://api.jquery.com/jQuery.ajax/#jQuery-ajax-settings">
+ * jQuery ajax settings</a>
+ */
compact: function(options) {
$.extend(options, {successStatus: 202});
ajax({
@@ -195,6 +318,15 @@
"The database could not be compacted"
);
},
+
+ /**
+ * Cleans up the cached view output on disk for a given view.
+ * @see <a href="http://techzone.couchbase.com/sites/default/files/
+ * uploads/all/documentation/couchbase-api-db.html#couchbase-api-db
+ * _db-view-cleanup_post">docs for /db/_compact</a>
+ * @param {ajaxSettings} options <a href="http://api.jquery.com/
+ * jQuery.ajax/#jQuery-ajax-settings">jQuery ajax settings</a>
+ */
viewCleanup: function(options) {
$.extend(options, {successStatus: 202});
ajax({
@@ -205,6 +337,19 @@
"The views could not be cleaned up"
);
},
+
+ /**
+ * Compacts the view indexes associated with the specified design
+ * document. You can use this in place of the full database compaction
+ * if you know a specific set of view indexes have been affected by a
+ * recent database change.
+ * @see <a href="http://techzone.couchbase.com/sites/default/files/upl
+ * oads/all/documentation/couchbase-api-db.html#couchbase-api-db_db-
+ * compact-design-doc_post">docs for /db/_compact/design-doc</a>
+ * @param {String} groupname Name of design-doc to compact
+ * @param {ajaxSettings} options <a href="http://api.jquery.com/
+ * jQuery.ajax/#jQuery-ajax-settings">jQuery ajax settings</a>
+ */
compactView: function(groupname, options) {
$.extend(options, {successStatus: 202});
ajax({
@@ -215,6 +360,15 @@
"The view could not be compacted"
);
},
+
+ /**
+ * Create a new database
+ * @see <a href="http://techzone.couchbase.com/sites/default/files/
+ * uploads/all/documentation/couchbase-api-db.html#couchbase-api-db_
+ * db_put">docs for PUT /db/</a>
+ * @param {ajaxSettings} options <a href="http://api.jquery.com/
+ * jQuery.ajax/#jQuery-ajax-settings">jQuery ajax settings</a>
+ */
create: function(options) {
$.extend(options, {successStatus: 201});
ajax({
@@ -225,6 +379,16 @@
"The database could not be created"
);
},
+
+ /**
+ * Deletes the specified database, and all the documents and
+ * attachments contained within it.
+ * @see <a href="http://techzone.couchbase.com/sites/default/files/
+ * uploads/all/documentation/couchbase-api-db.html#couchbase-api-db_
+ * db_delete">docs for DELETE /db/</a>
+ * @param {ajaxSettings} options <a href="http://api.jquery.com/
+ * jQuery.ajax/#jQuery-ajax-settings">jQuery ajax settings</a>
+ */
drop: function(options) {
ajax(
{type: "DELETE", url: this.uri},
@@ -232,6 +396,15 @@
"The database could not be deleted"
);
},
+
+ /**
+ * Gets information about the specified database.
+ * @see <a href="http://techzone.couchbase.com/sites/default/files/
+ * uploads/all/documentation/couchbase-api-db.html#couchbase-api-db
+ * _db_get">docs for GET /db/</a>
+ * @param {ajaxSettings} options <a href="http://api.jquery.com/
+ * jQuery.ajax/#jQuery-ajax-settings">jQuery ajax settings</a>
+ */
info: function(options) {
ajax(
{url: this.uri},
@@ -239,15 +412,39 @@
"Database information could not be retrieved"
);
},
+
+ /**
+ * @namespace
+ * $.couch.db.changes provides an API for subscribing to the changes
+ * feed
+ * <pre><code>var $changes = $.couch.db("mydatabase").changes();
+ *$changes.onChange = function (data) {
+ * ... process data ...
+ * }
+ * $changes.stop();
+ * </code></pre>
+ */
changes: function(since, options) {
+
options = options || {};
// set up the promise object within a closure for this handler
var timeout = 100, db = this, active = true,
listeners = [],
- promise = {
+ promise = /** @lends $.couch.db.changes */ {
+ /**
+ * Add a listener callback
+ * @see <a href="http://techzone.couchbase.com/sites/default/
+ * files/uploads/all/documentation/couchbase-api-db.html#couch
+ * base-api-db_db-changes_get">docs for /db/_changes</a>
+ * @param {Function} fun Callback function to run when
+ * notified of changes.
+ */
onChange : function(fun) {
listeners.push(fun);
},
+ /**
+ * Stop subscribing to the changes feed
+ */
stop : function() {
active = false;
}
@@ -258,7 +455,8 @@
this(resp);
});
};
- // when there is a change, call any listeners, then check for another change
+ // when there is a change, call any listeners, then check for
+ // another change
options.success = function(resp) {
timeout = 100;
if (active) {
@@ -298,6 +496,18 @@
}
return promise;
},
+
+ /**
+ * Fetch all the docs in this db, you can specify an array of keys to
+ * fetch by passing the <code>keys</code> field in the
+ * <code>options</code>
+ * parameter.
+ * @see <a href="http://techzone.couchbase.com/sites/default/files/
+ * uploads/all/documentation/couchbase-api-db.html#couchbase-api-db_
+ * db-all-docs_get">docs for /db/all_docs/</a>
+ * @param {ajaxSettings} options <a href="http://api.jquery.com/
+ * jQuery.ajax/#jQuery-ajax-settings">jQuery ajax settings</a>
+ */
allDocs: function(options) {
var type = "GET";
var data = null;
@@ -316,9 +526,24 @@
"An error occurred retrieving a list of all documents"
);
},
+
+ /**
+ * Fetch all the design docs in this db
+ * @param {ajaxSettings} options <a href="http://api.jquery.com/
+ * jQuery.ajax/#jQuery-ajax-settings">jQuery ajax settings</a>
+ */
allDesignDocs: function(options) {
- this.allDocs($.extend({startkey:"_design", endkey:"_design0"}, options));
+ this.allDocs($.extend(
+ {startkey:"_design", endkey:"_design0"}, options));
},
+
+ /**
+ * Fetch all the design docs with an index.html, <code>options</code>
+ * parameter expects an <code>eachApp</code> field which is a callback
+ * called on each app found.
+ * @param {ajaxSettings} options <a href="http://api.jquery.com/
+ * jQuery.ajax/#jQuery-ajax-settings">jQuery ajax settings</a>
+ */
allApps: function(options) {
options = options || {};
var self = this;
@@ -334,7 +559,8 @@
index = ddoc.couchapp && ddoc.couchapp.index;
if (index) {
appPath = ['', name, ddoc._id, index].join('/');
- } else if (ddoc._attachments && ddoc._attachments["index.html"]) {
+ } else if (ddoc._attachments &&
+ ddoc._attachments["index.html"]) {
appPath = ['', name, ddoc._id, "index.html"].join('/');
}
if (appPath) options.eachApp(appName, appPath, ddoc);
@@ -347,6 +573,18 @@
alert("Please provide an eachApp function for allApps()");
}
},
+
+ /**
+ * Returns the specified doc from the specified db.
+ * @see <a href="http://techzone.couchbase.com/sites/default/files/
+ * uploads/all/documentation/couchbase-api-dbdoc.html#couchbase-api-
+ * dbdoc_db-doc_get">docs for GET /db/doc</a>
+ * @param {String} docId id of document to fetch
+ * @param {ajaxSettings} options <a href="http://api.jquery.com/
+ * jQuery.ajax/#jQuery-ajax-settings">jQuery ajax settings</a>
+ * @param {ajaxSettings} ajaxOptions <a href="http://api.jquery.com/
+ * jQuery.ajax/#jQuery-ajax-settings">jQuery ajax settings</a>
+ */
openDoc: function(docId, options, ajaxOptions) {
options = options || {};
if (db_opts.attachPrevRev || options.attachPrevRev) {
@@ -376,6 +614,20 @@
ajaxOptions
);
},
+
+ /**
+ * Create a new document in the specified database, using the supplied
+ * JSON document structure. If the JSON structure includes the _id
+ * field, then the document will be created with the specified document
+ * ID. If the _id field is not specified, a new unique ID will be
+ * generated.
+ * @see <a href="http://techzone.couchbase.com/sites/default/files/
+ * uploads/all/documentation/couchbase-api-dbdoc.html#couchbase-api-
+ * dbdoc_db_post">docs for GET /db/doc</a>
+ * @param {String} doc document to save
+ * @param {ajaxSettings} options <a href="http://api.jquery.com/
+ * jQuery.ajax/#jQuery-ajax-settings">jQuery ajax settings</a>
+ */
saveDoc: function(doc, options) {
options = options || {};
var db = this;
@@ -417,6 +669,16 @@
}
});
},
+
+ /**
+ * Save a list of documents
+ * @see <a href="http://techzone.couchbase.com/sites/default/files/
+ * uploads/all/documentation/couchbase-api-db.html#couchbase-api-db_
+ * db-bulk-docs_post">docs for /db/_bulk_docs</a>
+ * @param {Object[]} docs List of documents to save
+ * @param {ajaxSettings} options <a href="http://api.jquery.com/
+ * jQuery.ajax/#jQuery-ajax-settings">jQuery ajax settings</a>
+ */
bulkSave: function(docs, options) {
var beforeSend = fullCommit(options);
$.extend(options, {successStatus: 201, beforeSend : beforeSend});
@@ -429,6 +691,18 @@
"The documents could not be saved"
);
},
+
+ /**
+ * Deletes the specified document from the database. You must supply
+ * the current (latest) revision and <code>id</code> of the document
+ * to delete eg <code>removeDoc({_id:"mydoc", _rev: "1-2345"})</code>
+ * @see <a href="http://techzone.couchbase.com/sites/default/files/
+ * uploads/all/documentation/couchbase-api-dbdoc.html#couchbase-api
+ * -dbdoc_db-doc_delete">docs for DELETE /db/doc</a>
+ * @param {Object} doc Document to delete
+ * @param {ajaxSettings} options <a href="http://api.jquery.com/
+ * jQuery.ajax/#jQuery-ajax-settings">jQuery ajax settings</a>
+ */
removeDoc: function(doc, options) {
ajax({
type: "DELETE",
@@ -440,6 +714,16 @@
"The document could not be deleted"
);
},
+
+ /**
+ * Remove a set of documents
+ * @see <a href="http://techzone.couchbase.com/sites/default/files/
+ * uploads/all/documentation/couchbase-api-db.html#couchbase-api-db_
+ * db-bulk-docs_post">docs for /db/_bulk_docs</a>
+ * @param {String[]} docs List of document id's to remove
+ * @param {ajaxSettings} options <a href="http://api.jquery.com/
+ * jQuery.ajax/#jQuery-ajax-settings">jQuery ajax settings</a>
+ */
bulkRemove: function(docs, options){
docs.docs = $.each(
docs.docs, function(i, doc){
@@ -456,6 +740,19 @@
"The documents could not be deleted"
);
},
+
+ /**
+ * The COPY command (which is non-standard HTTP) copies an existing
+ * document to a new or existing document.
+ * @see <a href="http://techzone.couchbase.com/sites/default/files/
+ * uploads/all/documentation/couchbase-api-dbdoc.html#couchbase-api-
+ * dbdoc_db-doc_copy">docs for COPY /db/doc</a>
+ * @param {String[]} docId document id to copy
+ * @param {ajaxSettings} options <a href="http://api.jquery.com/
+ * jQuery.ajax/#jQuery-ajax-settings">jQuery ajax settings</a>
+ * @param {ajaxSettings} options <a href="http://api.jquery.com/
+ * jQuery.ajax/#jQuery-ajax-settings">jQuery ajax settings</a>
+ */
copyDoc: function(docId, options, ajaxOptions) {
ajaxOptions = $.extend(ajaxOptions, {
complete: function(req) {
@@ -478,15 +775,31 @@
ajaxOptions
);
},
+
+ /**
+ * Creates (and executes) a temporary view based on the view function
+ * supplied in the JSON request.
+ * @see <a href="http://techzone.couchbase.com/sites/default/files/
+ * uploads/all/documentation/couchbase-api-db.html#couchbase-api-db
+ * _db-temp-view_post">docs for /db/_temp_view</a>
+ * @param {Function} mapFun Map function
+ * @param {Function} reduceFun Reduce function
+ * @param {Function} language Language the map / reduce funs are
+ * implemented in
+ * @param {ajaxSettings} options <a href="http://api.jquery.com/
+ * jQuery.ajax/#jQuery-ajax-settings">jQuery ajax settings</a>
+ */
query: function(mapFun, reduceFun, language, options) {
language = language || "javascript";
if (typeof(mapFun) !== "string") {
- mapFun = mapFun.toSource ? mapFun.toSource() : "(" + mapFun.toString() + ")";
+ mapFun = mapFun.toSource ? mapFun.toSource()
+ : "(" + mapFun.toString() + ")";
}
var body = {language: language, map: mapFun};
if (reduceFun != null) {
if (typeof(reduceFun) !== "string")
- reduceFun = reduceFun.toSource ? reduceFun.toSource() : "(" + reduceFun.toString() + ")";
+ reduceFun = reduceFun.toSource ? reduceFun.toSource()
+ : "(" + reduceFun.toString() + ")";
body.reduce = reduceFun;
}
ajax({
@@ -498,6 +811,19 @@
"An error occurred querying the database"
);
},
+
+ /**
+ * Fetch a _list view output, you can specify a list of
+ * <code>keys</code> in the options object to recieve only those keys.
+ * @see <a href="http://techzone.couchbase.com/sites/default/files/
+ * uploads/all/documentation/couchbase-api-design.html#couchbase-api
+ * -design_db-design-designdoc-list-listname-viewname_get">
+ * docs for /db/_design/design-doc/_list/l1/v1</a>
+ * @param {String} list Listname in the form of ddoc/listname
+ * @param {String} view View to run list against
+ * @param {ajaxSettings} options <a href="http://api.jquery.com/
+ * jQuery.ajax/#jQuery-ajax-settings">jQuery ajax settings</a>
+ */
list: function(list, view, options) {
var list = list.split('/');
var options = options || {};
@@ -518,6 +844,19 @@
options, 'An error occured accessing the list'
);
},
+
+ /**
+ * Executes the specified view-name from the specified design-doc
+ * design document, you can specify a list of <code>keys</code>
+ * in the options object to recieve only those keys.
+ * @see <a href="http://techzone.couchbase.com/sites/default/files/
+ * uploads/all/documentation/couchbase-api-design.html#couchbase-api-
+ * design_db-design-designdoc-view-viewname_get">docs for /db/
+ * _design/design-doc/_list/l1/v1</a>
+ * @param {String} name View to run list against
+ * @param {ajaxSettings} options <a href="http://api.jquery.com/
+ * jQuery.ajax/#jQuery-ajax-settings">jQuery ajax settings</a>
+ */
view: function(name, options) {
var name = name.split('/');
var options = options || {};
@@ -538,6 +877,17 @@
options, "An error occurred accessing the view"
);
},
+
+ /**
+ * Fetch an arbitrary CouchDB database property
+ * @see <a href="http://techzone.couchbase.com/sites/default/files/
+ * uploads/all/documentation/couchbase-api.html">docs for /db/_prop</a>
+ * @param {String} propName Propery name to fetch
+ * @param {ajaxSettings} options <a href="http://api.jquery.com/
+ * jQuery.ajax/#jQuery-ajax-settings">jQuery ajax settings</a>
+ * @param {ajaxSettings} ajaxOptions <a href="http://api.jquery.com/
+ * jQuery.ajax/#jQuery-ajax-settings">jQuery ajax settings</a>
+ */
getDbProperty: function(propName, options, ajaxOptions) {
ajax({url: this.uri + propName + encodeOptions(options)},
options,
@@ -546,6 +896,17 @@
);
},
+ /**
+ * Set an arbitrary CouchDB database property
+ * @see <a href="http://techzone.couchbase.com/sites/default/files/
+ * uploads/all/documentation/couchbase-api.html">docs for /db/_prop</a>
+ * @param {String} propName Propery name to fetch
+ * @param {String} propValue Propery value to set
+ * @param {ajaxSettings} options <a href="http://api.jquery.com/
+ * jQuery.ajax/#jQuery-ajax-settings">jQuery ajax settings</a>
+ * @param {ajaxSettings} ajaxOptions <a href="http://api.jquery.com/
+ * jQuery.ajax/#jQuery-ajax-settings">jQuery ajax settings</a>
+ */
setDbProperty: function(propName, propValue, options, ajaxOptions) {
ajax({
type: "PUT",
@@ -562,6 +923,17 @@
encodeDocId: encodeDocId,
+ /**
+ * Accessing the root of a CouchDB instance returns meta information about
+ * the instance. The response is a JSON structure containing information
+ * about the server, including a welcome message and the version of the
+ * server.
+ * @see <a href="http://techzone.couchbase.com/sites/default/files/uploads/
+ * all/documentation/couchbase-api-misc.html#couchbase-api-misc_root_get">
+ * docs for GET /</a>
+ * @param {ajaxSettings} options <a href="http://api.jquery.com/
+ * jQuery.ajax/#jQuery-ajax-settings">jQuery ajax settings</a>
+ */
info: function(options) {
ajax(
{url: this.urlPrefix + "/"},
@@ -570,6 +942,17 @@
);
},
+ /**
+ * Request, configure, or stop, a replication operation.
+ * @see <a href="http://techzone.couchbase.com/sites/default/files/
+ * uploads/all/documentation/couchbase-api-misc.html#couchbase-api-
+ * misc_replicate_post">docs for POST /_replicate</a>
+ * @param {String} source Path or url to source database
+ * @param {String} target Path or url to target database
+ * @param {ajaxSettings} ajaxOptions <a href="http://api.jquery.com/
+ * jQuery.ajax/#jQuery-ajax-settings">jQuery ajax settings</a>
+ * @param {Object} repOpts Additional replication options
+ */
replicate: function(source, target, ajaxOptions, repOpts) {
repOpts = $.extend({source: source, target: target}, repOpts);
if (repOpts.continuous && !repOpts.cancel) {
@@ -585,12 +968,20 @@
);
},
+ /**
+ * Fetch a new UUID
+ * @see <a href="http://techzone.couchbase.com/sites/default/files/
+ * uploads/all/documentation/couchbase-api-misc.html#couchbase-api-
+ * misc_uuids_get">docs for /_uuids</a>
+ * @param {Int} cacheNum Number of uuids to keep cached for future use
+ */
newUUID: function(cacheNum) {
if (cacheNum === undefined) {
cacheNum = 1;
}
if (!uuidCache.length) {
- ajax({url: this.urlPrefix + "/_uuids", data: {count: cacheNum}, async: false}, {
+ ajax({url: this.urlPrefix + "/_uuids", data: {count: cacheNum}, async:
+ false}, {
success: function(resp) {
uuidCache = resp.uuids;
}
@@ -616,13 +1007,17 @@
if ( typeof data === "string" ) {
if ( type === "json" || !type && ct.indexOf("json") >= 0 ) {
data = $.parseJSON( data );
- } else if ( type === "script" || !type && ct.indexOf("javascript") >= 0 ) {
+ } else if ( type === "script" ||
+ !type && ct.indexOf("javascript") >= 0 ) {
$.globalEval( data );
}
}
return data;
};
+ /**
+ * @private
+ */
function ajax(obj, options, errorMessage, ajaxOptions) {
options = $.extend({successStatus: 200}, options);
ajaxOptions = $.extend({contentType: "application/json"}, ajaxOptions);
@@ -654,7 +1049,8 @@
if (options.beforeSuccess) options.beforeSuccess(req, resp);
if (options.success) options.success(resp);
} else if (options.error) {
- options.error(req.status, resp && resp.error || errorMessage, resp && resp.reason || "no response");
+ options.error(req.status, resp && resp.error ||
+ errorMessage, resp && resp.reason || "no response");
} else {
alert(errorMessage + ": " + resp.reason);
}
@@ -662,6 +1058,9 @@
}, obj), ajaxOptions));
}
+ /**
+ * @private
+ */
function fullCommit(options) {
var options = options || {};
if (typeof options.ensure_full_commit !== "undefined") {
@@ -674,13 +1073,17 @@
}
};
+ /**
+ * @private
+ */
// Convert a options object to an url query string.
// ex: {key:'value',key2:'value2'} becomes '?key="value"&key2="value2"'
function encodeOptions(options) {
var buf = [];
if (typeof(options) === "object" && options !== null) {
for (var name in options) {
- if ($.inArray(name, ["error", "success", "beforeSuccess", "ajaxStart"]) >= 0)
+ if ($.inArray(name,
+ ["error", "success", "beforeSuccess", "ajaxStart"]) >= 0)
continue;
var value = options[name];
if ($.inArray(name, ["key", "startkey", "endkey"]) >= 0) {
@@ -692,6 +1095,9 @@
return buf.length ? "?" + buf.join("&") : "";
}
+ /**
+ * @private
+ */
function toJSON(obj) {
return obj !== null ? JSON.stringify(obj) : null;
}