Update wmts-hidpi, add nicer-api-docs

nicer-api-docs/closure-library/closure/goog/db/db.js

@@ -0,0 +1,182 @@
+// Copyright 2011 The Closure Library Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS-IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @fileoverview Wrappers for the HTML5 IndexedDB. The wrappers export nearly
+ * the same interface as the standard API, but return goog.async.Deferred
+ * objects instead of request objects and use Closure events. The wrapper works
+ * and has been tested on Chrome version 22+. It may work on older Chrome
+ * versions, but they aren't explicitly supported.
+ *
+ * Example usage:
+ *
+ *  <code>
+ *  goog.db.openDatabase('mydb', 1, function(ev, db, tx) {
+ *    db.createObjectStore('mystore');
+ *  }).addCallback(function(db) {
+ *    var putTx = db.createTransaction(
+ *        [],
+ *        goog.db.Transaction.TransactionMode.READ_WRITE);
+ *    var store = putTx.objectStore('mystore');
+ *    store.put('value', 'key');
+ *    goog.listen(putTx, goog.db.Transaction.EventTypes.COMPLETE, function() {
+ *      var getTx = db.createTransaction([]);
+ *      var request = getTx.objectStore('mystore').get('key');
+ *      request.addCallback(function(result) {
+ *        ...
+ *      });
+ *  });
+ *  </code>
+ *
+ */
+
+
+goog.provide('goog.db');
+
+goog.require('goog.async.Deferred');
+goog.require('goog.db.Error');
+goog.require('goog.db.IndexedDb');
+goog.require('goog.db.Transaction');
+
+
+/**
+ * The IndexedDB factory object.
+ *
+ * @type {IDBFactory}
+ * @private
+ */
+goog.db.indexedDb_ = goog.global.indexedDB || goog.global.mozIndexedDB ||
+    goog.global.webkitIndexedDB || goog.global.moz_indexedDB;
+
+
+/**
+ * A callback that's called if a blocked event is received. When a database is
+ * supposed to be deleted or upgraded (i.e. versionchange), and there are open
+ * connections to this database, a block event will be fired to prevent the
+ * operations from going through until all such open connections are closed.
+ * This callback can be used to notify users that they should close other tabs
+ * that have open connections, or to close the connections manually. Databases
+ * can also listen for the {@link goog.db.IndexedDb.EventType.VERSION_CHANGE}
+ * event to automatically close themselves when they're blocking such
+ * operations.
+ *
+ * This is passed a VersionChangeEvent that has the version of the database
+ * before it was deleted, and "null" as the new version.
+ *
+ * @typedef {function(!goog.db.IndexedDb.VersionChangeEvent)}
+ */
+goog.db.BlockedCallback;
+
+
+/**
+ * A callback that's called when opening a database whose internal version is
+ * lower than the version passed to {@link goog.db.openDatabase}.
+ *
+ * This callback is passed three arguments: a VersionChangeEvent with both the
+ * old version and the new version of the database; the database that's being
+ * opened, for which you can create and delete object stores; and the version
+ * change transaction, with which you can abort the version change.
+ *
+ * Note that the transaction is not active, which means that it can't be used to
+ * make changes to the database. However, since there is a transaction running,
+ * you can't create another one via {@link goog.db.IndexedDb.createTransaction}.
+ * This means that it's not possible to manipulate the database other than
+ * creating or removing object stores in this callback.
+ *
+ * @typedef {function(!goog.db.IndexedDb.VersionChangeEvent,
+ *                    !goog.db.IndexedDb,
+ *                    !goog.db.Transaction)}
+ */
+goog.db.UpgradeNeededCallback;
+
+
+/**
+ * Opens a database connection and wraps it.
+ *
+ * @param {string} name The name of the database to open.
+ * @param {number=} opt_version The expected version of the database. If this is
+ *     larger than the actual version, opt_onUpgradeNeeded will be called
+ *     (possibly after opt_onBlocked; see {@link goog.db.BlockedCallback}). If
+ *     this is passed, opt_onUpgradeNeeded must be passed as well.
+ * @param {goog.db.UpgradeNeededCallback=} opt_onUpgradeNeeded Called if
+ *     opt_version is greater than the old version of the database. If
+ *     opt_version is passed, this must be passed as well.
+ * @param {goog.db.BlockedCallback=} opt_onBlocked Called if there are active
+ *     connections to the database.
+ * @return {!goog.async.Deferred} The deferred database object.
+ */
+goog.db.openDatabase = function(name, opt_version, opt_onUpgradeNeeded,
+                                opt_onBlocked) {
+  goog.asserts.assert(
+      goog.isDef(opt_version) == goog.isDef(opt_onUpgradeNeeded),
+      'opt_version must be passed to goog.db.openDatabase if and only if ' +
+          'opt_onUpgradeNeeded is also passed');
+
+  var d = new goog.async.Deferred();
+  var openRequest = opt_version ?
+      goog.db.indexedDb_.open(name, opt_version) :
+      goog.db.indexedDb_.open(name);
+  openRequest.onsuccess = function(ev) {
+    var db = new goog.db.IndexedDb(ev.target.result);
+    d.callback(db);
+  };
+  openRequest.onerror = function(ev) {
+    var msg = 'opening database ' + name;
+    d.errback(goog.db.Error.fromRequest(ev.target, msg));
+  };
+  openRequest.onupgradeneeded = function(ev) {
+    if (!opt_onUpgradeNeeded) return;
+    var db = new goog.db.IndexedDb(ev.target.result);
+    opt_onUpgradeNeeded(
+        new goog.db.IndexedDb.VersionChangeEvent(ev.oldVersion, ev.newVersion),
+        db,
+        new goog.db.Transaction(ev.target.transaction, db));
+  };
+  openRequest.onblocked = function(ev) {
+    if (opt_onBlocked) {
+      opt_onBlocked(new goog.db.IndexedDb.VersionChangeEvent(
+          ev.oldVersion, ev.newVersion));
+    }
+  };
+  return d;
+};
+
+
+/**
+ * Deletes a database once all open connections have been closed.
+ *
+ * @param {string} name The name of the database to delete.
+ * @param {goog.db.BlockedCallback=} opt_onBlocked Called if there are active
+ *     connections to the database.
+ * @return {goog.async.Deferred} A deferred object that will fire once the
+ *     database is deleted.
+ */
+goog.db.deleteDatabase = function(name, opt_onBlocked) {
+  var d = new goog.async.Deferred();
+  var deleteRequest = goog.db.indexedDb_.deleteDatabase(name);
+  deleteRequest.onsuccess = function(ev) {
+    d.callback();
+  };
+  deleteRequest.onerror = function(ev) {
+    var msg = 'deleting database ' + name;
+    d.errback(goog.db.Error.fromRequest(ev.target, msg));
+  };
+  deleteRequest.onblocked = function(ev) {
+    if (opt_onBlocked) {
+      opt_onBlocked(new goog.db.IndexedDb.VersionChangeEvent(
+          ev.oldVersion, ev.newVersion));
+    }
+  };
+  return d;
+};